<
em>TestString</
em> <
em>CondPattern</
em></
code></
td></
tr>
<
tr><
th><
a href="directive-dict.html#Context">Context:</
a></
th><
td>server config, virtual host, directory, .htaccess</
td></
tr>
<
p>The <
code class="directive">RewriteCond</
code> directive defines a
rule condition. One or more <
code class="directive">RewriteCond</
code>
can precede a <
code class="directive"><
a href="#rewriterule">RewriteRule</
a></
code>
directive. The following rule is then only used if both
the current state of the URI matches its pattern, <
strong>and</
strong> if these conditions are met.</
p>
<
p><
em>TestString</
em> is a string which can contain the
following expanded constructs in addition to plain text:</
p>
<
strong>RewriteRule backreferences</
strong>: These are
backreferences of the form <
strong><
code>$N</
code></
strong>
(0 <= N <= 9). $1 to $9 provide access to the grouped
parts (in parentheses) of the pattern, from the
<
code>RewriteRule</
code> which is subject to the current
set of <
code>RewriteCond</
code> conditions. $0 provides
access to the whole string matched by that pattern.
<
strong>RewriteCond backreferences</
strong>: These are
backreferences of the form <
strong><
code>%N</
code></
strong>
(0 <= N <= 9). %1 to %9 provide access to the grouped
parts (again, in parentheses) of the pattern, from the last matched
<
code>RewriteCond</
code> in the current set
of conditions. %0 provides access to the whole string matched by
<
strong>RewriteMap expansions</
strong>: These are
expansions of the form <
strong><
code>${mapname:key|default}</
code></
strong>.
See <
a href="#mapfunc">the documentation for
RewriteMap</
a> for more details.
<
strong>Server-Variables</
strong>: These are variables of
<
strong><
code>%{</
code> <
em>NAME_OF_VARIABLE</
em>
where <
em>NAME_OF_VARIABLE</
em> can be a string taken
<
th>HTTP headers:</
th> <
th>connection & request:</
th> <
th />
HTTP_PROXY_CONNECTION<
br />
<
th>server internals:</
th> <
th>date and time:</
th> <
th>specials:</
th>
correspond to the similarly named HTTP
MIME-headers, C variables of the Apache HTTP Server or
<
code>struct tm</
code> fields of the Unix system.
Most are documented elsewhere in the Manual or in
the CGI specification. Those that are special to
mod_rewrite include those below.</
p>
<
dt><
code>IS_SUBREQ</
code></
dt>
<
dd>Will contain the text "true" if the request
currently being processed is a sub-request,
"false" otherwise. Sub-requests may be generated
by modules that need to resolve additional files
or URIs in order to complete their tasks.</
dd>
<
dt><
code>API_VERSION</
code></
dt>
<
dd>This is the version of the Apache httpd module API
(the internal interface between server and
module) in the current httpd build, as defined in
corresponds to the version of Apache httpd in use (in
the release version of Apache httpd 1.3.14, for
instance, it is 19990320:10), but is mainly of
interest to module authors.</
dd>
<
dt><
code>THE_REQUEST</
code></
dt>
<
dd>The full HTTP request line sent by the
browser to the server (
e.g., "<
code>GET
include any additional headers sent by the
<
dt><
code>REQUEST_URI</
code></
dt>
<
dd>The resource requested in the HTTP request
line. (In the example above, this would be
<
dt><
code>REQUEST_FILENAME</
code></
dt>
<
dd>The full local filesystem path to the file or
script matching the request, if this has already
been determined by the server at the time
<
code>REQUEST_FILENAME</
code> is referenced. Otherwise,
such as when used in virtual host context, the same
value as <
code>REQUEST_URI</
code>.</
dd>
<
dt><
code>HTTPS</
code></
dt>
<
dd>Will contain the text "on" if the connection is
using
SSL/
TLS, or "off" otherwise. (This variable
can be safely used regardless of whether or not
<
code class="module"><
a href="/mod/mod_ssl.html">mod_ssl</
a></
code> is loaded).</
dd>
<
p>Other things you should be aware of:</
p>
<
p>The variables SCRIPT_FILENAME and REQUEST_FILENAME
contain the same value - the value of the
<
code>filename</
code> field of the internal
<
code>request_rec</
code> structure of the Apache HTTP Server.
The first name is the commonly known CGI variable name
while the second is the appropriate counterpart of
REQUEST_URI (which contains the value of the
<
code>uri</
code> field of <
code>request_rec</
code>).</
p>
<
p>If a substitution occurred and the rewriting continues,
the value of both variables will be updated accordingly.</
p>
<
p>If used in per-server context (<
em>
i.e.</
em>, before the
request is mapped to the filesystem) SCRIPT_FILENAME and
REQUEST_FILENAME cannot contain the full local filesystem
path since the path is unknown at this stage of processing.
Both variables will initially contain the value of REQUEST_URI
in that case. In order to obtain the full local filesystem
path of the request in per-server context, use an URL-based
look-ahead <
code>%{LA-U:REQUEST_FILENAME}</
code> to determine
the final value of REQUEST_FILENAME.</
p></
li>
<
code>%{ENV:variable}</
code>, where <
em>variable</
em> can be
any environment variable, is also available.
This is looked-up via internal
Apache httpd structures and (if not found there) via
<
code>getenv()</
code> from the Apache httpd server process.</
li>
<
code>%{SSL:variable}</
code>, where <
em>variable</
em> is the
variable</
a>, can be used whether or not
<
code class="module"><
a href="/mod/mod_ssl.html">mod_ssl</
a></
code> is loaded, but will always expand to
the empty string if it is not. Example:
<
code>%{SSL:SSL_CIPHER_USEKEYSIZE}</
code> may expand to
<
code>%{HTTP:header}</
code>, where <
em>header</
em> can be
any HTTP MIME-header name, can always be used to obtain the
value of a header sent in the HTTP request.
Example: <
code>%{HTTP:Proxy-Connection}</
code> is
the value of the HTTP header
``<
code>Proxy-Connection:</
code>''.
<
p>If a HTTP header is used in a condition this header is added to
the Vary header of the response in case the condition evaluates to
to true for the request. It is <
strong>not</
strong> added if the
condition evaluates to false for the request. Adding the HTTP header
to the Vary header of the response is needed for proper caching.</
p>
<
p>It has to be kept in mind that conditions follow a short circuit
logic in the case of the '<
strong><
code>ornext|OR</
code></
strong>' flag
so that certain conditions might not be evaluated at all.</
p></
li>
<
code>%{LA-U:variable}</
code> can be used for look-aheads which perform
an internal (URL-based) sub-request to determine the final
value of <
em>variable</
em>. This can be used to access
variable for rewriting which is not available at the current
stage, but will be set in a later phase.
<
p>For instance, to rewrite according to the
<
code>REMOTE_USER</
code> variable from within the
per-server context (<
code>
httpd.conf</
code> file) you must
use <
code>%{LA-U:REMOTE_USER}</
code> - this
variable is set by the authorization phases, which come
<
em>after</
em> the URL translation phase (during which mod_rewrite
<
p>On the other hand, because mod_rewrite implements
its per-directory context (<
code>.htaccess</
code> file) via
the Fixup phase of the API and because the authorization
phases come <
em>before</
em> this phase, you just can use
<
code>%{REMOTE_USER}</
code> in that context.</
p></
li>
<
code>%{LA-F:variable}</
code> can be used to perform an internal
(filename-based) sub-request, to determine the final value
of <
em>variable</
em>. Most of the time, this is the same as
<
p><
em>CondPattern</
em> is the condition pattern,
a regular expression which is applied to the
current instance of the <
em>TestString</
em>.
<
em>TestString</
em> is first evaluated, before being matched against
<
em>CondPattern</
em>.</
p>
<
p><
strong>Remember:</
strong> <
em>CondPattern</
em> is a
<
em>perl compatible regular expression</
em> with some
<
li>You can prefix the pattern string with a
'<
code>!</
code>' character (exclamation mark) to specify a
<
strong>non</
strong>-matching pattern.</
li>
There are some special variants of <
em>CondPatterns</
em>.
Instead of real regular expression strings you can also
use one of the following:
<
li>'<
strong><CondPattern</
strong>' (lexicographically
Treats the <
em>CondPattern</
em> as a plain string and
compares it lexicographically to <
em>TestString</
em>. True if
<
em>TestString</
em> lexicographically precedes
<
em>CondPattern</
em>.</
li>
<
li>'<
strong>>CondPattern</
strong>' (lexicographically
Treats the <
em>CondPattern</
em> as a plain string and
compares it lexicographically to <
em>TestString</
em>. True if
<
em>TestString</
em> lexicographically follows
<
em>CondPattern</
em>.</
li>
<
li>'<
strong>=CondPattern</
strong>' (lexicographically
Treats the <
em>CondPattern</
em> as a plain string and
compares it lexicographically to <
em>TestString</
em>. True if
<
em>TestString</
em> is lexicographically equal to
<
em>CondPattern</
em> (the two strings are exactly
equal, character for character). If <
em>CondPattern</
em>
is <
code>""</
code> (two quotation marks) this
compares <
em>TestString</
em> to the empty string.</
li>
<
li>'<
strong>-d</
strong>' (is
<
strong>d</
strong>irectory)<
br />
Treats the <
em>TestString</
em> as a pathname and tests
whether or not it exists, and is a directory.</
li>
<
li>'<
strong>-f</
strong>' (is regular
<
strong>f</
strong>ile)<
br />
Treats the <
em>TestString</
em> as a pathname and tests
whether or not it exists, and is a regular file.</
li>
<
li>'<
strong>-s</
strong>' (is regular file, with
<
strong>s</
strong>ize)<
br />
Treats the <
em>TestString</
em> as a pathname and tests
whether or not it exists, and is a regular file with size greater
<
li>'<
strong>-l</
strong>' (is symbolic
<
strong>l</
strong>ink)<
br />
Treats the <
em>TestString</
em> as a pathname and tests
whether or not it exists, and is a symbolic link.</
li>
<
li>'<
strong>-x</
strong>' (has e<
strong>x</
strong>ecutable
Treats the <
em>TestString</
em> as a pathname and tests
whether or not it exists, and has executable permissions.
These permissions are determined according to
<
li>'<
strong>-F</
strong>' (is existing file, via
Checks whether or not <
em>TestString</
em> is a valid file,
accessible via all the server's currently-configured
access controls for that path. This uses an internal
subrequest to do the check, so use it with care -
it can impact your server's performance!</
li>
<
li>'<
strong>-U</
strong>' (is existing URL, via
Checks whether or not <
em>TestString</
em> is a valid URL,
accessible via all the server's currently-configured
access controls for that path. This uses an internal
subrequest to do the check, so use it with care -
it can impact your server's performance!</
li>
<
div class="note"><
h3>Note:</
h3>
also be prefixed by an exclamation mark ('!') to
<
li>You can also set special flags for
<
em>CondPattern</
em> by appending
<
strong><
code>[</
code><
em>flags</
em><
code>]</
code></
strong>
as the third argument to the <
code>RewriteCond</
code>
directive, where <
em>flags</
em> is a comma-separated list of any of the
<
li>'<
strong><
code>nocase|NC</
code></
strong>'
(<
strong>n</
strong>o <
strong>c</
strong>ase)<
br />
This makes the test case-insensitive - differences
between 'A-Z' and 'a-z' are ignored, both in the
expanded <
em>TestString</
em> and the <
em>CondPattern</
em>.
This flag is effective only for comparisons between
<
em>TestString</
em> and <
em>CondPattern</
em>. It has no
effect on filesystem and subrequest checks.</
li>
'<
strong><
code>ornext|OR</
code></
strong>'
(<
strong>or</
strong> next condition)<
br />
Use this to combine rule conditions with a local OR
instead of the implicit AND. Typical example:
<
div class="example"><
pre>
RewriteCond %{REMOTE_HOST} ^host1.* [OR]
RewriteCond %{REMOTE_HOST} ^host2.* [OR]
RewriteCond %{REMOTE_HOST} ^host3.*
RewriteRule
...some special stuff for any of these hosts...
<
li>'<
strong><
code>novary|NV</
code></
strong>'
(<
strong>n</
strong>o <
strong>v</
strong>ary)<
br />
If a HTTP header is used in the condition, this flag prevents
this header from being added to the Vary header of the response. <
br />
Using this flag might break proper caching of the response if
the representation of this response varies on the value of this header.
So this flag should be only used if the meaning of the Vary header
<
p><
strong>Example:</
strong></
p>
<
p>To rewrite the Homepage of a site according to the
``<
code>User-Agent:</
code>'' header of the request, you can
<
div class="example"><
pre>
RewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
RewriteCond %{HTTP_USER_AGENT} ^Lynx.*
<
p>Explanation: If you use a browser which identifies itself
as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you
get the max homepage (which could include frames, or other special
If you use the Lynx browser (which is terminal-based), then
you get the min homepage (which could be a version designed for
easy, text-only browsing).
If neither of these conditions apply (you use any other browser,
or your browser identifies itself as something non-standard), you get
the std (standard) homepage.</
p>
<
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
<
div class="directive-section"><
h2><
a name="RewriteEngine" id="RewriteEngine">RewriteEngine</
a> <
a name="rewriteengine" id="rewriteengine">Directive</
a></
h2>
<
table class="directive">
<
tr><
th><
a href="directive-dict.html#Description">Description:</
a></
th><
td>Enables or disables runtime rewriting engine</
td></
tr>
<
tr><
th><
a href="directive-dict.html#Syntax">Syntax:</
a></
th><
td><
code>RewriteEngine on|off</
code></
td></
tr>
<
tr><
th><
a href="directive-dict.html#Default">Default:</
a></
th><
td><
code>RewriteEngine off</
code></
td></
tr>
<
tr><
th><
a href="directive-dict.html#Context">Context:</
a></
th><
td>server config, virtual host, directory, .htaccess</
td></
tr>
<
p>The <
code class="directive">RewriteEngine</
code> directive enables or
disables the runtime rewriting engine. If it is set to
<
code>off</
code> this module does no runtime processing at
all. It does not even update the <
code>SCRIPT_URx</
code>
environment variables.</
p>
<
p>Use this directive to disable the module instead of
commenting out all the <
code class="directive"><
a href="#rewriterule">RewriteRule</
a></
code> directives!</
p>
<
p>Note that rewrite configurations are not
inherited by virtual hosts. This means that you need to have a
<
code>RewriteEngine on</
code> directive for each virtual host
in which you wish to use rewrite rules.</
p>
<
p><
code class="directive">RewriteMap</
code> directives of the type <
code>prg</
code>
are not started during server initialization if they're defined in a
context that does not have <
code class="directive">RewriteEngine</
code> set to
<
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
<
div class="directive-section"><
h2><
a name="RewriteLog" id="RewriteLog">RewriteLog</
a> <
a name="rewritelog" id="rewritelog">Directive</
a></
h2>
<
table class="directive">
<
tr><
th><
a href="directive-dict.html#Description">Description:</
a></
th><
td>Sets the name of the file used for logging rewrite engine
<
tr><
th><
a href="directive-dict.html#Syntax">Syntax:</
a></
th><
td><
code>RewriteLog <
em>file-path</
em></
code></
td></
tr>
<
tr><
th><
a href="directive-dict.html#Context">Context:</
a></
th><
td>server config, virtual host</
td></
tr>
<
p>The <
code class="directive">RewriteLog</
code> directive sets the name
of the file to which the server logs any rewriting actions it
performs. If the name does not begin with a slash
('<
code>/</
code>') then it is assumed to be relative to the
<
em>Server Root</
em>. The directive should occur only once per
<
div class="note"> To disable the logging of
rewriting actions it is not recommended to set
<
em>Filename</
em> to <
code>/
dev/
null</
code>, because
although the rewriting engine does not then output to a
logfile it still creates the logfile output internally.
<
strong>This will slow down the server with no advantage
to the administrator!</
strong> To disable logging either
remove or comment out the <
code class="directive">RewriteLog</
code>
directive or use <
code>RewriteLogLevel 0</
code>!
<
div class="note"><
h3>Security</
h3>
document for details on how your security could be compromised if the
directory where logfiles are stored is writable by anyone other than
the user that starts the server.
<
div class="example"><
h3>Example</
h3><
p><
code>
<
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
<
div class="directive-section"><
h2><
a name="RewriteLogLevel" id="RewriteLogLevel">RewriteLogLevel</
a> <
a name="rewriteloglevel" id="rewriteloglevel">Directive</
a></
h2>
<
table class="directive">
<
tr><
th><
a href="directive-dict.html#Description">Description:</
a></
th><
td>Sets the verbosity of the log file used by the rewrite
<
tr><
th><
a href="directive-dict.html#Syntax">Syntax:</
a></
th><
td><
code>RewriteLogLevel <
em>Level</
em></
code></
td></
tr>
<
tr><
th><
a href="directive-dict.html#Default">Default:</
a></
th><
td><
code>RewriteLogLevel 0</
code></
td></
tr>
<
tr><
th><
a href="directive-dict.html#Context">Context:</
a></
th><
td>server config, virtual host</
td></
tr>
<
p>The <
code class="directive">RewriteLogLevel</
code> directive sets the
verbosity level of the rewriting logfile. The default level 0
means no logging, while 9 or more means that practically all
<
p>To disable the logging of rewriting actions simply set
<
em>Level</
em> to 0. This disables all rewrite action
<
div class="note"> Using a high value for
<
em>Level</
em> will slow down your Apache HTTP Server
dramatically! Use the rewriting logfile at a
<
em>Level</
em> greater than 2 only for debugging!
<
div class="example"><
h3>Example</
h3><
p><
code>
<
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
<
div class="directive-section"><
h2><
a name="RewriteMap" id="RewriteMap">RewriteMap</
a> <
a name="rewritemap" id="rewritemap">Directive</
a></
h2>
<
table class="directive">
<
tr><
th><
a href="directive-dict.html#Description">Description:</
a></
th><
td>Defines a mapping function for key-lookup</
td></
tr>
<
tr><
th><
a href="directive-dict.html#Syntax">Syntax:</
a></
th><
td><
code>RewriteMap <
em>MapName</
em> <
em>MapType</
em>:<
em>MapSource</
em>
<
tr><
th><
a href="directive-dict.html#Context">Context:</
a></
th><
td>server config, virtual host</
td></
tr>
<
tr><
th><
a href="directive-dict.html#Compatibility">Compatibility:</
a></
th><
td>The choice of different dbm types is available in
Apache HTTP Server 2.0.41 and later</
td></
tr>
<
p>The <
code class="directive">RewriteMap</
code> directive defines a
<
em>Rewriting Map</
em> which can be used inside rule
substitution strings by the mapping-functions to
this lookup can be of various types.</
p>
<
p>The <
a id="mapfunc" name="mapfunc"><
em>MapName</
em></
a> is
the name of the map and will be used to specify a
mapping-function for the substitution strings of a rewriting
rule via one of the following constructs:</
p>
<
strong><
code>${</
code> <
em>MapName</
em> <
code>:</
code>
<
em>LookupKey</
em> <
code>}</
code><
br />
<
code>${</
code> <
em>MapName</
em> <
code>:</
code>
<
em>LookupKey</
em> <
code>|</
code> <
em>DefaultValue</
em>
<
p>When such a construct occurs, the map <
em>MapName</
em> is
consulted and the key <
em>LookupKey</
em> is looked-up. If the
key is found, the map-function construct is substituted by
<
em>SubstValue</
em>. If the key is not found then it is
substituted by <
em>DefaultValue</
em> or by the empty string
if no <
em>DefaultValue</
em> was specified.</
p>
<
p>For example, you might define a
<
code class="directive">RewriteMap</
code> as:</
p>
<
div class="example"><
p><
code>
<
p>You would then be able to use this map in a
<
code class="directive">RewriteRule</
code> as follows:</
p>
<
div class="example"><
p><
code>
RewriteRule ^/ex/(.*) ${examplemap:$1}
<
p>The following combinations for <
em>MapType</
em> and
<
em>MapSource</
em> can be used:</
p>
<
strong>Standard Plain Text</
strong><
br />
MapType: <
code>txt</
code>, MapSource: Unix filesystem
path to valid regular file
<
p>This is the standard rewriting map feature where the
<
em>MapSource</
em> is a plain ASCII file containing
either blank lines, comment lines (starting with a '#'
character) or pairs like the following - one per
<
strong><
em>MatchingKey</
em>
<
em>SubstValue</
em></
strong>
<
div class="example"><
h3>Example</
h3><
pre>
<
div class="example"><
p><
code>
<
strong>Randomized Plain Text</
strong><
br />
MapType: <
code>rnd</
code>, MapSource: Unix filesystem
path to valid regular file
<
p>This is identical to the Standard Plain Text variant
above but with a special post-processing feature: After
looking up a value it is parsed according to contained
``<
code>|</
code>'' characters which have the meaning of
``or''. In other words they indicate a set of
alternatives from which the actual returned value is
chosen randomly. For example, you might use the following map
file and directives to provide a random load balancing between
several back-end server, via a reverse-proxy. Images are sent
to one of the servers in the 'static' pool, while everything
else is sent to one of the 'dynamic' pool.</
p>
<
div class="example"><
h3>Rewrite map file</
h3><
pre>
static www1|www2|www3|www4
<
div class="example"><
h3>Configuration directives</
h3><
p><
code>
RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
<
strong>Hash File</
strong><
br /> MapType:
<
code>dbm[=<
em>type</
em>]</
code>, MapSource: Unix filesystem
path to valid regular file
<
p>Here the source is a binary format DBM file containing
the same contents as a <
em>Plain Text</
em> format file, but
in a special representation which is optimized for really
fast lookups. The <
em>type</
em> can be sdbm, gdbm, ndbm, or
settings</
a>. If the <
em>type</
em> is omitted, the
compile-time default will be chosen.</
p>
<
p>To create a dbm file from a source text file, use the <
a href="/programs/httxt2dbm.html">httxt2dbm</
a> utility.</
p>
<
div class="example"><
p><
code>
<
strong>Internal Function</
strong><
br />
MapType: <
code>int</
code>, MapSource: Internal Apache httpd
<
p>Here, the source is an internal Apache httpd function.
Currently you cannot create your own, but the following
functions already exist:</
p>
<
li><
strong>toupper</
strong>:<
br />
Converts the key to all upper case.</
li>
<
li><
strong>tolower</
strong>:<
br />
Converts the key to all lower case.</
li>
<
li><
strong>escape</
strong>:<
br />
Translates special characters in the key to
<
li><
strong>unescape</
strong>:<
br />
Translates hex-encodings in the key back to
<
strong>External Rewriting Program</
strong><
br />
MapType: <
code>prg</
code>, MapSource: Unix filesystem
path to valid regular file
<
p>Here the source is a program, not a map file. To
create it you can use a language of your choice, but
the result has to be an executable program (either
object-code or a script with the magic cookie trick
<
p>This program is started once, when the Apache httpd server
is started, and then communicates with the rewriting engine
via its <
code>stdin</
code> and <
code>stdout</
code>
file-handles. For each map-function lookup it will
receive the key to lookup as a newline-terminated string
on <
code>stdin</
code>. It then has to give back the
looked-up value as a newline-terminated string on
<
code>stdout</
code> or the four-character string
``<
code>NULL</
code>'' if it fails (<
em>
i.e.</
em>, there
is no corresponding value for the given key).</
p>
<
p>This feature utilizes the <
code>rewrite-map</
code> mutex,
which is required for reliable communication with the program.
The mutex mechanism and lock file can be configured with the
<
code class="directive"><
a href="/mod/core.html#mutex">Mutex</
a></
code> directive.</
p>
<
p>External rewriting programs are not started if they're defined in a
context that does not have <
code class="directive">RewriteEngine</
code> set to
<
p>A trivial program which will implement a 1:1 map (<
em>
i.e.</
em>,
key == value) could be:</
p>
<
div class="example"><
pre>
#
...put here any transformations or lookups...
<
p>But be very careful:</
p>
<
li>``<
em>Keep it simple, stupid</
em>'' (KISS).
If this program hangs, it will cause Apache httpd to hang
when trying to use the relevant rewrite rule.</
li>
<
li>A common mistake is to use buffered I/O on
<
code>stdout</
code>. Avoid this, as it will cause a deadloop!
``<
code>$|=1</
code>'' is used above, to prevent this.</
li>
<
p><
strong>SQL Query</
strong><
br />
MapType: <
code>dbd</
code> or <
code>fastdbd</
code>,
MapSource: An SQL SELECT statement that takes a single
argument and returns a single value.</
p>
<
p>This uses <
code class="module"><
a href="/mod/mod_dbd.html">mod_dbd</
a></
code> to implement a rewritemap
by lookup in an SQL database. There are two forms:
<
code>fastdbd</
code> caches database lookups internally,
<
code>dbd</
code> doesn't. So <
code>dbd</
code> incurs a
performance penalty but responds immediately if the database
contents are updated, while <
code>fastdbd</
code> is more
efficient but won't re-read database contents until server
<
p>If a query returns more than one row, a random row from
the result set is used.</
p>
<
div class="example"><
h3>Example</
h3><
p><
code>
RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
<
p>The <
code class="directive">RewriteMap</
code> directive can occur more than
once. For each mapping-function use one
<
code class="directive">RewriteMap</
code> directive to declare its rewriting
mapfile. While you cannot <
strong>declare</
strong> a map in
per-directory context it is of course possible to
<
strong>use</
strong> this map in per-directory context. </
p>
<
div class="note"><
h3>Note</
h3> For plain text and DBM format files the
looked-up keys are cached in-core until the <
code>mtime</
code> of the
mapfile changes or the server does a restart. This way you can have
map-functions in rules which are used for <
strong>every</
strong>
request. This is no problem, because the external lookup only happens
<
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
<
div class="directive-section"><
h2><
a name="RewriteOptions" id="RewriteOptions">RewriteOptions</
a> <
a name="rewriteoptions" id="rewriteoptions">Directive</
a></
h2>
<
table class="directive">
<
tr><
th><
a href="directive-dict.html#Description">Description:</
a></
th><
td>Sets some special options for the rewrite engine</
td></
tr>
<
tr><
th><
a href="directive-dict.html#Syntax">Syntax:</
a></
th><
td><
code>RewriteOptions <
var>Options</
var></
code></
td></
tr>
<
tr><
th><
a href="directive-dict.html#Context">Context:</
a></
th><
td>server config, virtual host, directory, .htaccess</
td></
tr>
<
tr><
th><
a href="directive-dict.html#Compatibility">Compatibility:</
a></
th><
td><
code>MaxRedirects</
code> is no longer available in version 2.1 and
<
p>The <
code class="directive">RewriteOptions</
code> directive sets some
special options for the current per-server or per-directory
configuration. The <
em>Option</
em> string can currently
only be one of the following:</
p>
<
dt><
code>inherit</
code></
dt>
<
dd>This forces the current configuration to inherit the
configuration of the parent. In per-virtual-server context,
this means that the maps, conditions and rules of the main
server are inherited. In per-directory context this means
that conditions and rules of the parent directory's
<
code>.htaccess</
code> configuration or
<
code class="directive"><
a href="/mod/core.html#directory"><Directory></
a></
code>
sections are inherited. The inherited rules are virtually copied
to the section where this directive is being used. If used in
combination with local rules, the inherited rules are copied behind
the local rules. The position of this directive - below or above
of local rules - has no influence on this behavior. If local
rules forced the rewriting to stop, the inherited rules won't
<
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
<
div class="directive-section"><
h2><
a name="RewriteRule" id="RewriteRule">RewriteRule</
a> <
a name="rewriterule" id="rewriterule">Directive</
a></
h2>
<
table class="directive">
<
tr><
th><
a href="directive-dict.html#Description">Description:</
a></
th><
td>Defines rules for the rewriting engine</
td></
tr>
<
em>Pattern</
em> <
em>Substitution</
em> [<
em>flags</
em>]</
code></
td></
tr>
<
tr><
th><
a href="directive-dict.html#Context">Context:</
a></
th><
td>server config, virtual host, directory, .htaccess</
td></
tr>
<
p>The <
code class="directive">RewriteRule</
code> directive is the real
rewriting workhorse. The directive can occur more than once,
with each instance defining a single rewrite rule. The
order in which these rules are defined is important - this is the order
in which they will be applied at run-time.</
p>
<
p><
a id="patterns" name="patterns"><
em>Pattern</
em></
a> is
a perl compatible <
a id="regexp" name="regexp">regular
expression</
a>. On the first RewriteRule it is applied to the (%-encoded)
subsequent patterns are applied to the output of the last matched
<
div class="note"><
h3>What is matched?</
h3>
<
p>The <
em>Pattern</
em> will initially be matched against the part of the
URL after the hostname and port, and before the query string.</
p>
<
p>When the RewriteRule appears in per-directory (htaccess) context, the
<
em>Pattern</
em> is matched against what remains of the URL after removing
the prefix that lead Apache httpd to the current rules (see the
<
code class="directive"><
a href="#rewritebase">RewriteBase</
a></
code>). The removed prefix
always ends with a slash, meaning the matching occurs against a string which
never has a leading slash. A <
em>Pattern</
em> with <
code>^/</
code> never
matches in per-directory context.</
p>
<
p>If you wish to match against the hostname, port, or query string, use a
<
code class="directive"><
a href="#rewritecond">RewriteCond</
a></
code> with the
<
code>%{HTTP_HOST}</
code>, <
code>%{SERVER_PORT}</
code>, or
<
code>%{QUERY_STRING}</
code> variables respectively. If you wish to
match against the full URL-path in a per-directory (htaccess) RewriteRule,
use the <
code>%{REQUEST_URI}</
code> variable.</
p>
<
p>For some hints on <
a class="glossarylink" href="/glossary.html#regex" title="see glossary">regular
<
p>In mod_rewrite, the NOT character
('<
code>!</
code>') is also available as a possible pattern
prefix. This enables you to negate a pattern; to say, for instance:
``<
em>if the current URL does <
strong>NOT</
strong> match this
pattern</
em>''. This can be used for exceptional cases, where
it is easier to match the negative pattern, or as a last
<
div class="note"><
h3>Note</
h3>
When using the NOT character to negate a pattern, you cannot include
grouped wildcard parts in that pattern. This is because, when the
pattern does NOT match (ie, the negation matches), there are no
contents for the groups. Thus, if negated patterns are used, you
cannot use <
code>$N</
code> in the substitution string!
<
p>The <
a id="rhs" name="rhs"><
em>Substitution</
em></
a> of a
rewrite rule is the string that replaces the original URL-path that
was matched by <
em>Pattern</
em>. The <
em>Substitution</
em> may
<
dt>file-system path</
dt>
<
dd>Designates the location on the file-system of the resource
to be delivered to the client.</
dd>
<
dd>A <
code class="directive"><
a href="/mod/core.html#documentroot">DocumentRoot</
a></
code>-relative path to the
resource to be served. Note that <
code class="module"><
a href="/mod/mod_rewrite.html">mod_rewrite</
a></
code>
tries to guess whether you have specified a file-system path
or a URL-path by checking to see if the first segment of the
path exists at the root of the file-system. For example, if
you specify a <
em>Substitution</
em> string of
URL-path <
em>unless</
em> a directory named <
code>www</
code>
exists at the root or your file-system, in which case it will
be treated as a file-system path. If you wish other
URL-mapping directives (such as <
code class="directive"><
a href="/mod/mod_alias.html#alias">Alias</
a></
code>) to be applied to the
resulting URL-path, use the <
code>[PT]</
code> flag as
<
dd>If an absolute URL is specified,
<
code class="module"><
a href="/mod/mod_rewrite.html">mod_rewrite</
a></
code> checks to see whether the
hostname matches the current host. If it does, the scheme and
hostname are stripped out and the resulting path is treated as
a URL-path. Otherwise, an external redirect is performed for
the given URL. To force an external redirect back to the
current host, see the <
code>[R]</
code> flag below.</
dd>
<
dt><
code>-</
code> (dash)</
dt>
<
dd>A dash indicates that no substitution should be performed
(the existing path is passed through untouched). This is used
when a flag (see below) needs to be applied without changing
<
p>In addition to plain text, the <
em>Substition</
em> string can include</
p>
<
li>back-references (<
code>$N</
code>) to the RewriteRule
<
li>back-references (<
code>%N</
code>) to the last matched
<
li>server-variables as in rule condition test-strings
(<
code>%{VARNAME}</
code>)</
li>
<
li><
a href="#mapfunc">mapping-function</
a> calls
(<
code>${mapname:key|default}</
code>)</
li>
<
p>Back-references are identifiers of the form
<
code>$</
code><
strong>N</
strong>
(<
strong>N</
strong>=0..9), which will be replaced
by the contents of the <
strong>N</
strong>th group of the
matched <
em>Pattern</
em>. The server-variables are the same
as for the <
em>TestString</
em> of a <
code>RewriteCond</
code>
directive. The mapping-functions come from the
<
code>RewriteMap</
code> directive and are explained there.
These three types of variables are expanded in the order above.</
p>
<
p>As already mentioned, all rewrite rules are
applied to the <
em>Substitution</
em> (in the order in which
in the config file). The URL is <
strong>completely
replaced</
strong> by the <
em>Substitution</
em> and the
rewriting process continues until all rules have been applied,
or it is explicitly terminated by a
<
code><
strong>L</
strong></
code> flag.</
p>
<
div class="note"><
h3>Modifying the Query String</
h3>
<
p>By default, the query string is passed through unchanged. You
can, however, create URLs in the substitution string containing
a query string part. Simply use a question mark inside the
substitution string to indicate that the following text should
be re-injected into the query string. When you want to erase an
existing query string, end the substitution string with just a
question mark. To combine new and old query strings, use the
<
code>[QSA]</
code> flag.</
p>
<
p>Additionally you can set special <
a name="rewriteflags" id="rewriteflags">actions</
a> to be performed by
appending <
strong><
code>[</
code><
em>flags</
em><
code>]</
code></
strong>
as the third argument to the <
code>RewriteRule</
code>
directive. <
em>Flags</
em> is a comma-separated list, surround by square
brackets, of any of the flags in the following table. More
details, and examples, for each flag, are available in the <
a href="/rewrite/flags.html">Rewrite Flags document</
a>.</
p>
<
tr><
th>Flag and syntax</
th>
<
td>Escape non-alphanumeric characters <
em>before</
em> applying
the transformation. <
em><
a href="/rewrite/flags.html#flag_b">details ...</
a></
em></
td>
<
td>Rule is chained to the following rule. If the rule fails,
the rule(s) chained to it will be skipped. <
em><
a href="/rewrite/flags.html#flag_c">details ...</
a></
em></
td>
<
td>cookie|CO=<
em>NAME</
em>:<
em>VAL</
em></
td>
<
td>Sets a cookie in the client browser. Full syntax is:
CO=<
em>NAME</
em>:<
em>VAL</
em>[:<
em>domain</
em>[:<
em>lifetime</
em>[:<
em>path</
em>[:<
em>secure</
em>[:<
em>httponly</
em>]]]]] <
em><
a href="/rewrite/flags.html#flag_co">details ...</
a></
em>
<
td>discardpathinfo|DPI</
td>
<
td>Causes the PATH_INFO portion of the rewritten URI to be
<
td>env|E=<
em>VAR</
em>:<
em>VAL</
em></
td>
<
td>Causes an environment variable <
em>VAR</
em> to be set to the
value <
em>VAL</
em>. <
em><
a href="/rewrite/flags.html#flag_e">details ...</
a></
em></
td>
<
td>Returns a 403 FORBIDDEN response to the client browser.
<
td>Returns a 410 GONE response to the client browser. <
em><
a href="/rewrite/flags.html#flag_g">details ...</
a></
em></
td>
<
td>Handler|H=<
em>Content-handler</
em></
td>
<
td>Causes the resulting URI to be sent to the specified
<
em>Content-handler</
em> for processing. <
em><
a href="/rewrite/flags.html#flag_h">details ...</
a></
em></
td>
<
td>Stop the rewriting process immediately and don't apply any
more rules. Especially note caveats for per-directory and
.htaccess context. <
em><
a href="/rewrite/flags.html#flag_l">details ...</
a></
em></
td>
<
td>Re-run the rewriting process, starting again with the first
rule, using the result of the ruleset so far as a starting
<
td>Makes the pattern pattern comparison case-insensitive.
<
td>Prevent mod_rewrite from applying hexcode escaping of
special characters in the result of the rewrite. <
em><
a href="/rewrite/flags.html#flag_ne">details ...</
a></
em></
td>
<
td>Causes a rule to be skipped if the current request is an
internal sub-request. <
em><
a href="/rewrite/flags.html#flag_ns">details ...</
a></
em></
td>
<
td>Force the substitution URL to be internally sent as a proxy
<
td>Forces the resulting URI to be passed back to the URL
mapping engine for processing of other URI-to-filename
translators, such as <
code>Alias</
code> or
<
code>Redirect</
code>. <
em><
a href="/rewrite/flags.html#flag_pt">details ...</
a></
em></
td>
<
td>Appends any query string created in the rewrite target to
any query string that was in the original request URL. <
em><
a href="/rewrite/flags.html#flag_qsa">details ...</
a></
em></
td>
<
td>Discard any query string attached to the incoming URI.
<
td>redirect|R[=<
em>code</
em>]</
td>
<
td>Forces an external redirect, optionally with the specified
<
td>skip|S=<
em>num</
em></
td>
<
td>Tells the rewriting engine to skip the next <
em>num</
em>
rules if the current rule matches. <
em><
a href="/rewrite/flags.html#flag_s">details ...</
a></
em></
td>
<
td>tyle|T=<
em>MIME-type</
em></
td>
<
td>Force the <
a class="glossarylink" href="/glossary.html#mime-type" title="see glossary">MIME-type</
a> of the target file
to be the specified type. <
em><
a href="/rewrite/flags.html#flag_t">details ...</
a></
em></
td>
<
div class="note"><
h3>Home directory expansion</
h3>
<
p> When the substitution string begins with a string
resembling "/~user" (via explicit text or backreferences), mod_rewrite performs
home directory expansion independent of the presence or configuration
<
p> This expansion does not occur when the <
em>PT</
em>
flag is used on the <
code class="directive"><
a href="#rewriterule">RewriteRule</
a></
code>
<
div class="note"><
h3>Per-directory Rewrites</
h3>
<
p>The rewrite engine may be used in <
a href="/howto/htaccess.html">.htaccess</
a> files. To enable the
rewrite engine for these files you need to set
"<
code>RewriteEngine On</
code>" <
strong>and</
strong>
"<
code>Options FollowSymLinks</
code>" must be enabled. If your
administrator has disabled override of <
code>FollowSymLinks</
code> for
a user's directory, then you cannot use the rewrite engine. This
restriction is required for security reasons.</
p>
<
p>When using the rewrite engine in <
code>.htaccess</
code> files the
per-directory prefix (which always is the same for a specific
directory) is automatically <
em>removed</
em> for the pattern matching
and automatically <
em>added</
em> after the substitution has been
done. This feature is essential for many sorts of rewriting; without
this, you would always have to match the parent directory, which is
not always possible. There is one exception: If a substitution string
starts with <
code>http://</
code>, then the directory prefix will
<
strong>not</
strong> be added, and an external redirect (or proxy
throughput, if using flag <
strong>P</
strong>) is forced. See the
<
code class="directive"><
a href="#rewritebase">RewriteBase</
a></
code> directive for
<
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
prefix-matching rules as would be applied to <
code>.htaccess</
code>
files. It is usually simpler, however, to avoid the prefix substitution
complication by putting the rewrite rules in the main server or
virtual host context, rather than in a <
code class="directive"><
a href="/mod/core.html#directory"><Directory></
a></
code> section.</
p>
<
p>Although rewrite rules are syntactically permitted in <
code class="directive"><
a href="/mod/core.html#location"><Location></
a></
code> and <
code class="directive"><
a href="/mod/core.html#files"><Files></
a></
code> sections, this
should never be necessary and is unsupported.</
p>
<
p>Here are all possible substitution combinations and their
<
p><
strong>Inside per-server configuration
<
strong>Given Rule</
strong> <
strong>Resulting Substitution</
strong>
---------------------------------------------- ----------------------------------
^/somepath(.*) otherpath$1 invalid, not supported
^/somepath(.*) otherpath$1 [R] invalid, not supported
^/somepath(.*) otherpath$1 [P] invalid, not supported
---------------------------------------------- ----------------------------------
^/somepath(.*) /otherpath$1 [P] doesn't make sense, not supported
---------------------------------------------- ----------------------------------
---------------------------------------------- ----------------------------------
(the [R] flag is redundant)
<
p><
strong>Inside per-directory configuration for
<
code>/somepath</
code><
br />
<
code>RewriteBase /somepath</
code>)<
br />
<
strong>Given Rule</
strong> <
strong>Resulting Substitution</
strong>
---------------------------------------------- ----------------------------------
^localpath(.*) otherpath$1 [P] doesn't make sense, not supported
---------------------------------------------- ----------------------------------
^localpath(.*) /otherpath$1 [P] doesn't make sense, not supported
---------------------------------------------- ----------------------------------
---------------------------------------------- ----------------------------------
(the [R] flag is redundant)
<
p><
span>Available Languages: </
span><
a href="/en/mod/mod_rewrite.html" title="English"> en </
a> |