60a4b2c422dcbb08a554fb193105c08da592718bpoirier<?xml version="1.0"?>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

3f08db06526d6901aa08c110b5bc7dde6bc39905nd

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<modulesynopsis metafile="mod_rewrite.xml.meta">

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<name>mod_rewrite</name>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<description>Provides a rule-based rewriting engine to rewrite requested

60a4b2c422dcbb08a554fb193105c08da592718bpoirierURLs on the fly</description>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick<status>Extension</status>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick<sourcefile>mod_rewrite.c</sourcefile>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick<identifier>rewrite_module</identifier>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick<summary>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <p>The <module>mod_rewrite</module> module uses a rule-based rewriting

60a4b2c422dcbb08a554fb193105c08da592718bpoirier engine, based on a regular-expression parser, to rewrite requested URLs on

60a4b2c422dcbb08a554fb193105c08da592718bpoirier the fly. By default, <module>mod_rewrite</module> maps a URL to a filesystem

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick path. However, it can also be used to redirect one URL to another URL, or

60a4b2c422dcbb08a554fb193105c08da592718bpoirier to invoke an internal proxy fetch.</p>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p><module>mod_rewrite</module> provides a flexible and powerful way to

60a4b2c422dcbb08a554fb193105c08da592718bpoirier manipulate URLs using an unlimited number of rules. Each rule can have an

60a4b2c422dcbb08a554fb193105c08da592718bpoirier unlimited number of attached rule conditions, to allow you to rewrite URL

60a4b2c422dcbb08a554fb193105c08da592718bpoirier based on server variables, environment variables, HTTP headers, or time

60a4b2c422dcbb08a554fb193105c08da592718bpoirier stamps.</p>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p><module>mod_rewrite</module> operates on the full URL path, including the

60a4b2c422dcbb08a554fb193105c08da592718bpoirier path-info section. A rewrite rule can be invoked in

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <code>httpd.conf</code> or in <code>.htaccess</code>. The path generated

60a4b2c422dcbb08a554fb193105c08da592718bpoirier by a rewrite rule can include a query string, or can lead to internal

60a4b2c422dcbb08a554fb193105c08da592718bpoirier sub-processing, external request redirection, or internal proxy

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf throughput.</p>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh <p>Further details, discussion, and examples, are provided in the

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <a href="/rewrite/">detailed mod_rewrite documentation</a>.</p>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier</summary>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<section id="logging"><title>Logging</title>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <p><module>mod_rewrite</module> offers detailed logging of its actions

60a4b2c422dcbb08a554fb193105c08da592718bpoirier at the <code>trace1</code> to <code>trace8</code> log levels. The

60a4b2c422dcbb08a554fb193105c08da592718bpoirier log level can be set specifically for <module>mod_rewrite</module>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier using the <directive module="core">LogLevel</directive> directive: Up to

60a4b2c422dcbb08a554fb193105c08da592718bpoirier level <code>debug</code>, no actions are logged, while <code>trace8</code>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf means that practically all actions are logged.</p>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <note>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier Using a high trace log level for <module>mod_rewrite</module>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick will slow down your Apache HTTP Server dramatically! Use a log

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick level higher than <code>trace2</code> only for debugging!

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf </note>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <example><title>Example</title>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier LogLevel alert rewrite:trace3

60a4b2c422dcbb08a554fb193105c08da592718bpoirier </example>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <note><title>RewriteLog</title>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <p>Those familiar with earlier versions of

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <module>mod_rewrite</module> will no doubt be looking for the

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <code>RewriteLog</code> and <code>RewriteLogLevel</code>

a04dcd330b05345681a4057702b2d43b2042e21dtrawick directives. This functionality has been completely replaced by the

a04dcd330b05345681a4057702b2d43b2042e21dtrawick new per-module logging configuration mentioned above.

a04dcd330b05345681a4057702b2d43b2042e21dtrawick </p>

a04dcd330b05345681a4057702b2d43b2042e21dtrawick

f8b7daeb0e3f0ac4544fcc665de10c6b69a1ce0dsf <p>To get just the <module>mod_rewrite</module>-specific log

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick messages, pipe the log file through grep:</p>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <example>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf tail -f error_log|fgrep '[rewrite:'

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf </example>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier </note>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick</section>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<directivesynopsis>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<name>RewriteEngine</name>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<description>Enables or disables runtime rewriting engine</description>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<syntax>RewriteEngine on|off</syntax>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<default>RewriteEngine off</default>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<contextlist><context>server config</context><context>virtual host</context>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<context>directory</context><context>.htaccess</context></contextlist>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<override>FileInfo</override>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<usage>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

bed3c2e56e8f3328e780200466b9d009093db468sf <p>The <directive>RewriteEngine</directive> directive enables or

bed3c2e56e8f3328e780200466b9d009093db468sf disables the runtime rewriting engine. If it is set to

bed3c2e56e8f3328e780200466b9d009093db468sf <code>off</code> this module does no runtime processing at

bed3c2e56e8f3328e780200466b9d009093db468sf all. It does not even update the <code>SCRIPT_URx</code>

bed3c2e56e8f3328e780200466b9d009093db468sf environment variables.</p>

bed3c2e56e8f3328e780200466b9d009093db468sf

bed3c2e56e8f3328e780200466b9d009093db468sf <p>Use this directive to disable the module instead of

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf commenting out all the <directive

60a4b2c422dcbb08a554fb193105c08da592718bpoirier module="mod_rewrite">RewriteRule</directive> directives!</p>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>Note that rewrite configurations are not

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick inherited by virtual hosts. This means that you need to have a

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <code>RewriteEngine on</code> directive for each virtual host

60a4b2c422dcbb08a554fb193105c08da592718bpoirier in which you wish to use rewrite rules.</p>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <p><directive>RewriteMap</directive> directives of the type <code>prg</code>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick are not started during server initialization if they're defined in a

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick context that does not have <directive>RewriteEngine</directive> set to

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <code>on</code></p>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick</usage>

bcb2c4ef861e8f8260284631b6753e1088643c8asf

bcb2c4ef861e8f8260284631b6753e1088643c8asf</directivesynopsis>

bcb2c4ef861e8f8260284631b6753e1088643c8asf

bcb2c4ef861e8f8260284631b6753e1088643c8asf<directivesynopsis>

bcb2c4ef861e8f8260284631b6753e1088643c8asf<name>RewriteOptions</name>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<description>Sets some special options for the rewrite engine</description>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<syntax>RewriteOptions <var>Options</var></syntax>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<contextlist><context>server config</context><context>virtual host</context>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<context>directory</context><context>.htaccess</context></contextlist>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<override>FileInfo</override>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<compatibility><code>MaxRedirects</code> is no longer available in version 2.1 and

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawicklater</compatibility>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick<usage>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <p>The <directive>RewriteOptions</directive> directive sets some

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick special options for the current per-server or per-directory

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick configuration. The <em>Option</em> string can currently

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf only be one of the following:</p>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

57b31f30545668d28e895efe7f5c0eb15d37a03figalic <dl>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <dt><code>Inherit</code></dt>

d474d8ef01ec5c2a09341cd148851ed383c3287crbowen <dd>

d474d8ef01ec5c2a09341cd148851ed383c3287crbowen

d474d8ef01ec5c2a09341cd148851ed383c3287crbowen <p>This forces the current configuration to inherit the

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick configuration of the parent. In per-virtual-server context,

0236ede61169f34359c234625a1d792b97d7db12nd this means that the maps, conditions and rules of the main

0236ede61169f34359c234625a1d792b97d7db12nd server are inherited. In per-directory context this means

60a4b2c422dcbb08a554fb193105c08da592718bpoirier that conditions and rules of the parent directory's

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <code>.htaccess</code> configuration or

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <directive type="section" module="core">Directory</directive>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf sections are inherited. The inherited rules are virtually copied

60a4b2c422dcbb08a554fb193105c08da592718bpoirier to the section where this directive is being used. If used in

60a4b2c422dcbb08a554fb193105c08da592718bpoirier combination with local rules, the inherited rules are copied behind

60a4b2c422dcbb08a554fb193105c08da592718bpoirier the local rules. The position of this directive - below or above

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick of local rules - has no influence on this behavior. If local

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf rules forced the rewriting to stop, the inherited rules won't

60a4b2c422dcbb08a554fb193105c08da592718bpoirier be processed.</p>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <note type="warning">

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick Rules inherited from the parent scope are applied

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <strong>after</strong> rules specified in the child scope.

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick </note>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick </dd>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <dt><code>InheritBefore</code></dt>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <dd>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <p> Like <code>Inherit</code> above, but the rules from the parent scope

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick are applied <strong>before</strong> rules specified in the child scope.

60a4b2c422dcbb08a554fb193105c08da592718bpoirier Available in Apache HTTP Server 2.3.10 and later.</p>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf </dd>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf </dl>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

60a4b2c422dcbb08a554fb193105c08da592718bpoirier</usage>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick</directivesynopsis>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick<directivesynopsis>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick<name>RewriteMap</name>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<description>Defines a mapping function for key-lookup</description>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick<syntax>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick</syntax>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<contextlist><context>server config</context><context>virtual host</context>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf</contextlist>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<compatibility>The choice of different dbm types is available in

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sfApache HTTP Server 2.0.41 and later</compatibility>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<usage>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>The <directive>RewriteMap</directive> directive defines a

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <em>Rewriting Map</em> which can be used inside rule

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick substitution strings by the mapping-functions to

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick insert/substitute fields through a key lookup. The source of

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick this lookup can be of various types.</p>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick the name of the map and will be used to specify a

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick mapping-function for the substitution strings of a rewriting

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick rule via one of the following constructs:</p>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <p class="indent">

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <strong><code>${</code> <em>MapName</em> <code>:</code>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <em>LookupKey</em> <code>}</code><br />

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <code>${</code> <em>MapName</em> <code>:</code>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <code>}</code></strong>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier </p>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>When such a construct occurs, the map <em>MapName</em> is

60a4b2c422dcbb08a554fb193105c08da592718bpoirier consulted and the key <em>LookupKey</em> is looked-up. If the

60a4b2c422dcbb08a554fb193105c08da592718bpoirier key is found, the map-function construct is substituted by

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <em>SubstValue</em>. If the key is not found then it is

60a4b2c422dcbb08a554fb193105c08da592718bpoirier substituted by <em>DefaultValue</em> or by the empty string

60a4b2c422dcbb08a554fb193105c08da592718bpoirier if no <em>DefaultValue</em> was specified. Empty values

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick behave as if the key was absent, therefore it is not possible

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick to distinguish between empty-valued keys and absent keys.</p>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <p>For example, you might define a

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <directive>RewriteMap</directive> as:</p>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <example>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf RewriteMap examplemap txt:/path/to/file/map.txt

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf </example>

b6529ec5115d80b7dedcfd0935746015b2096084minfrin

b6529ec5115d80b7dedcfd0935746015b2096084minfrin <p>You would then be able to use this map in a

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <directive>RewriteRule</directive> as follows:</p>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <example>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick RewriteRule ^/ex/(.*) ${examplemap:$1}

b6529ec5115d80b7dedcfd0935746015b2096084minfrin </example>

b6529ec5115d80b7dedcfd0935746015b2096084minfrin

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <p>The following combinations for <em>MapType</em> and

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <em>MapSource</em> can be used:</p>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <dl>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <dt>txt</dt>

78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin <dd>A plain text file containing space-separated key-value

b6529ec5115d80b7dedcfd0935746015b2096084minfrin pairs, one per line. (<a href="/rewrite/rewritemap.html#txt">Details ...</a>)</dd>

b6529ec5115d80b7dedcfd0935746015b2096084minfrin

b6529ec5115d80b7dedcfd0935746015b2096084minfrin <dt>rnd</dt>

b6529ec5115d80b7dedcfd0935746015b2096084minfrin <dd>Randomly selects an entry from a plain text file (<a href="/rewrite/rewritemap.html#rnd">Details ...</a>)</dd>

b6529ec5115d80b7dedcfd0935746015b2096084minfrin

b6529ec5115d80b7dedcfd0935746015b2096084minfrin <dt>dbm</dt>

b6529ec5115d80b7dedcfd0935746015b2096084minfrin <dd>Looks up an entry in a dbm file containing name, value

78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin pairs. Hash is constructed from a plain text file format using

78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin the <code><a href="/programs/httxt2dbm.html">httxt2dbm</a></code>

78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin utility. (<a href="/rewrite/rewritemap.html#dbm">Details ...</a>)</dd>

78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin

78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin <dt>int</dt>

78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin <dd>One of the four available internal functions provided by

78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin <code>RewriteMap</code>: toupper, tolower, escape or

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf unescape. (<a href="/rewrite/rewritemap.html#int">Details ...</a>)</dd>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <dt>prg</dt>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <dd>Calls an external program or script to process the

60a4b2c422dcbb08a554fb193105c08da592718bpoirier rewriting. (<a href="/rewrite/rewritemap.html#prg">Details ...</a>)</dd>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <dt>dbd or fastdbd</dt>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <dd>A SQL SELECT statement to be performed to look up the

60a4b2c422dcbb08a554fb193105c08da592718bpoirier rewrite target. (<a href="/rewrite/rewritemap.html#dbd">Details ...</a>)</dd>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier </dl>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <p>Further details, and numerous examples, may be found in the <a

60a4b2c422dcbb08a554fb193105c08da592718bpoirier href="/rewrite/rewritemap.html">RewriteMap HowTo</a></p>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick</usage>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick</directivesynopsis>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick<directivesynopsis>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick<name>RewriteBase</name>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<description>Sets the base URL for per-directory rewrites</description>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<syntax>RewriteBase <em>URL-path</em></syntax>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<default>None</default>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<contextlist><context>directory</context><context>.htaccess</context>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier</contextlist>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick<override>FileInfo</override>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier

60a4b2c422dcbb08a554fb193105c08da592718bpoirier<usage>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <p>The <directive>RewriteBase</directive> directive explicitly

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf sets the base URL-path (not filesystem directory path!) for per-directory rewrites.

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf When you use a <directive module="mod_rewrite">RewriteRule</directive>

60a4b2c422dcbb08a554fb193105c08da592718bpoirier in a <code>.htaccess</code> file, <module>mod_rewrite</module> strips off

60a4b2c422dcbb08a554fb193105c08da592718bpoirier the local directory prefix before processing, then rewrites the rest of

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf the URL. When the rewrite is completed, <module>mod_rewrite</module>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf automatically adds the local directory prefix back on to the path.</p>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>This directive is <em>required</em> for per-directory rewrites whose context

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick is a directory made available via the <directive module="mod_alias">Alias</directive>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf directive.</p>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <p>If your URL path does not exist verbatim on the filesystem,

60a4b2c422dcbb08a554fb193105c08da592718bpoirier or isn't directly under your <directive module="core">DocumentRoot</directive>,

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick you must use <directive>RewriteBase</directive> in every

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <code>.htaccess</code> file where you want to use <directive

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick module="mod_rewrite">RewriteRule</directive> directives.</p>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <p>The example below demonstrates how to map

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf http://example.com/myapp/index.html to

60a4b2c422dcbb08a554fb193105c08da592718bpoirier /home/www/example/newsite.html, in a <code>.htaccess</code> file. This

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick assumes that the content available at

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf http://example.com/ is on disk at /home/www/example/</p>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<example>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<pre>

60a4b2c422dcbb08a554fb193105c08da592718bpoirierRewriteEngine On

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick# The URL-path used to get to this context, not the filesystem path

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sfRewriteBase /myapp/

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sfRewriteRule ^index\.html$ newsite.html

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf</pre>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf</example>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf</usage>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf</directivesynopsis>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<directivesynopsis>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<name>RewriteCond</name>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<description>Defines a condition under which rewriting will take place

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf</description>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<syntax> RewriteCond

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <em>TestString</em> <em>CondPattern</em></syntax>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<contextlist><context>server config</context><context>virtual host</context>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<context>directory</context><context>.htaccess</context></contextlist>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<override>FileInfo</override>

50c04f297d76a57ead2fa6b73845f7563b1fc788sf

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<usage>

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <p>The <directive>RewriteCond</directive> directive defines a

8cef90cad1b259d4a94f6095aa30439c60549a5drbowen rule condition. One or more <directive>RewriteCond</directive>

8cef90cad1b259d4a94f6095aa30439c60549a5drbowen can precede a <directive module="mod_rewrite">RewriteRule</directive>

8cef90cad1b259d4a94f6095aa30439c60549a5drbowen directive. The following rule is then only used if both

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf the current state of the URI matches its pattern, <strong

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf >and</strong> if these conditions are met.</p>

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <p><em>TestString</em> is a string which can contain the

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick following expanded constructs in addition to plain text:</p>

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <ul>

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <li>

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <strong>RewriteRule backreferences</strong>: These are

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick backreferences of the form <strong><code>$N</code></strong>

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick (0 &lt;= N &lt;= 9). $1 to $9 provide access to the grouped

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick parts (in parentheses) of the pattern, from the

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <code>RewriteRule</code> which is subject to the current

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick set of <code>RewriteCond</code> conditions. $0 provides

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick access to the whole string matched by that pattern.

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf </li>

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <li>

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <strong>RewriteCond backreferences</strong>: These are

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick backreferences of the form <strong><code>%N</code></strong>

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick (0 &lt;= N &lt;= 9). %1 to %9 provide access to the grouped

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick parts (again, in parentheses) of the pattern, from the last matched

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <code>RewriteCond</code> in the current set

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick of conditions. %0 provides access to the whole string matched by

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick that pattern.

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick </li>

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <li>

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <strong>RewriteMap expansions</strong>: These are

33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick expansions of the form <strong><code

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick >${mapname:key|default}</code></strong>.

5effc8b39fae5cd169d17f342bfc265705840014rbowen See <a href="#mapfunc">the documentation for

5effc8b39fae5cd169d17f342bfc265705840014rbowen RewriteMap</a> for more details.

5effc8b39fae5cd169d17f342bfc265705840014rbowen </li>

5effc8b39fae5cd169d17f342bfc265705840014rbowen <li>

5effc8b39fae5cd169d17f342bfc265705840014rbowen <strong>Server-Variables</strong>: These are variables of

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf the form

68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick <strong><code>%{</code> <em>NAME_OF_VARIABLE</em>

68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick <code>}</code></strong>

68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick where <em>NAME_OF_VARIABLE</em> can be a string taken

68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick from the following list:

68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick

68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick <table>

68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick <columnspec><column width=".3"/><column width=".3"/>

68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick <column width=".3"/></columnspec>

68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick <tr>

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <th>HTTP headers:</th> <th>connection &amp; request:</th> <th></th>

68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick </tr>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2509f1cd3be884abbe4852e15b8da00bebaad5b1poirier <tr>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <td>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick HTTP_USER_AGENT<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick HTTP_REFERER<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick HTTP_COOKIE<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick HTTP_FORWARDED<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick HTTP_HOST<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick HTTP_PROXY_CONNECTION<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick HTTP_ACCEPT<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick </td>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <td>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick REMOTE_ADDR<br />

2509f1cd3be884abbe4852e15b8da00bebaad5b1poirier REMOTE_HOST<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick REMOTE_PORT<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick REMOTE_USER<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick REMOTE_IDENT<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick REQUEST_METHOD<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick SCRIPT_FILENAME<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick PATH_INFO<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick QUERY_STRING<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick AUTH_TYPE<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick </td>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <td></td>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick </tr>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <tr>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <th>server internals:</th> <th>date and time:</th> <th>specials:</th>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick </tr>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <tr>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <td>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick DOCUMENT_ROOT<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick SERVER_ADMIN<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick SERVER_NAME<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick SERVER_ADDR<br />

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf SERVER_PORT<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick SERVER_PROTOCOL<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick SERVER_SOFTWARE<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick </td>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <td>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick TIME_YEAR<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick TIME_MON<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick TIME_DAY<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick TIME_HOUR<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick TIME_MIN<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick TIME_SEC<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick TIME_WDAY<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick TIME<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick </td>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <td>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick API_VERSION<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick THE_REQUEST<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick REQUEST_URI<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick REQUEST_FILENAME<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick IS_SUBREQ<br />

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick HTTPS<br />

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick </td>

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick </tr>

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick </table>

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick <p>These variables all

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick correspond to the similarly named HTTP

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick MIME-headers, C variables of the Apache HTTP Server or

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick <code>struct tm</code> fields of the Unix system.

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick Most are documented elsewhere in the Manual or in

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick the CGI specification. Those that are special to

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick mod_rewrite include those below.</p>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <note>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dl>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dt><code>IS_SUBREQ</code></dt>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>Will contain the text "true" if the request

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick currently being processed is a sub-request,

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick "false" otherwise. Sub-requests may be generated

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick by modules that need to resolve additional files

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick or URIs in order to complete their tasks.</dd>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dt><code>API_VERSION</code></dt>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>This is the version of the Apache httpd module API

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick (the internal interface between server and

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick module) in the current httpd build, as defined in

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick include/ap_mmn.h. The module API version

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick corresponds to the version of Apache httpd in use (in

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick the release version of Apache httpd 1.3.14, for

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick instance, it is 19990320:10), but is mainly of

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick interest to module authors.</dd>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dt><code>THE_REQUEST</code></dt>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>The full HTTP request line sent by the

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick browser to the server (e.g., "<code>GET

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick /index.html HTTP/1.1</code>"). This does not

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick include any additional headers sent by the

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick browser.</dd>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dt><code>REQUEST_URI</code></dt>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>The resource requested in the HTTP request

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick line. (In the example above, this would be

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick "/index.html".)</dd>

8cef90cad1b259d4a94f6095aa30439c60549a5drbowen

8cef90cad1b259d4a94f6095aa30439c60549a5drbowen <dt><code>REQUEST_FILENAME</code></dt>

8cef90cad1b259d4a94f6095aa30439c60549a5drbowen

8cef90cad1b259d4a94f6095aa30439c60549a5drbowen <dd>The full local filesystem path to the file or

8cef90cad1b259d4a94f6095aa30439c60549a5drbowen script matching the request, if this has already

8cef90cad1b259d4a94f6095aa30439c60549a5drbowen been determined by the server at the time

8cef90cad1b259d4a94f6095aa30439c60549a5drbowen <code>REQUEST_FILENAME</code> is referenced. Otherwise,

8cef90cad1b259d4a94f6095aa30439c60549a5drbowen such as when used in virtual host context, the same

8cef90cad1b259d4a94f6095aa30439c60549a5drbowen value as <code>REQUEST_URI</code>.</dd>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dt><code>HTTPS</code></dt>

46fc29754beed5aa71b9dd9a69a85cc840b307f8minfrin

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <dd>Will contain the text "on" if the connection is

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick using SSL/TLS, or "off" otherwise. (This variable

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick can be safely used regardless of whether or not

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <module>mod_ssl</module> is loaded).</dd>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick </dl>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick</note>

46fc29754beed5aa71b9dd9a69a85cc840b307f8minfrin </li>

9cb641b95a976f28161ff3eb5dc71105a8f75ddeminfrin </ul>

9cb641b95a976f28161ff3eb5dc71105a8f75ddeminfrin

46fc29754beed5aa71b9dd9a69a85cc840b307f8minfrin <p>Other things you should be aware of:</p>

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <ol>

c8ea2fd531ec56b7969ee48fc05655b503fa57a3minfrin <li>

c8ea2fd531ec56b7969ee48fc05655b503fa57a3minfrin <p>The variables SCRIPT_FILENAME and REQUEST_FILENAME

46fc29754beed5aa71b9dd9a69a85cc840b307f8minfrin contain the same value - the value of the

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <code>filename</code> field of the internal

b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <code>request_rec</code> structure of the Apache HTTP Server.

46fc29754beed5aa71b9dd9a69a85cc840b307f8minfrin The first name is the commonly known CGI variable name

46fc29754beed5aa71b9dd9a69a85cc840b307f8minfrin while the second is the appropriate counterpart of

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick REQUEST_URI (which contains the value of the

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <code>uri</code> field of <code>request_rec</code>).</p>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <p>If a substitution occurred and the rewriting continues,

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick the value of both variables will be updated accordingly.</p>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <p>If used in per-server context (<em>i.e.</em>, before the

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick request is mapped to the filesystem) SCRIPT_FILENAME and

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick REQUEST_FILENAME cannot contain the full local filesystem

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick path since the path is unknown at this stage of processing.

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick Both variables will initially contain the value of REQUEST_URI

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick in that case. In order to obtain the full local filesystem

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick path of the request in per-server context, use an URL-based

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick look-ahead <code>%{LA-U:REQUEST_FILENAME}</code> to determine

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick the final value of REQUEST_FILENAME.</p></li>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <li>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <code>%{ENV:variable}</code>, where <em>variable</em> can be

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick any environment variable, is also available.

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick This is looked-up via internal

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick Apache httpd structures and (if not found there) via

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <code>getenv()</code> from the Apache httpd server process.</li>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <li>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <code>%{SSL:variable}</code>, where <em>variable</em> is the

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick name of an <a href="mod_ssl.html#envvars">SSL environment

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick variable</a>, can be used whether or not

2509f1cd3be884abbe4852e15b8da00bebaad5b1poirier <module>mod_ssl</module> is loaded, but will always expand to

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick the empty string if it is not. Example:

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <code>%{SSL:SSL_CIPHER_USEKEYSIZE}</code> may expand to

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <code>128</code>.</li>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <li>

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <code>%{HTTP:header}</code>, where <em>header</em> can be

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick any HTTP MIME-header name, can always be used to obtain the

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick value of a header sent in the HTTP request.

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick Example: <code>%{HTTP:Proxy-Connection}</code> is

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick the value of the HTTP header

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick ``<code>Proxy-Connection:</code>''.

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <p>If a HTTP header is used in a condition this header is added to

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick the Vary header of the response in case the condition evaluates to

2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick to true for the request. It is <strong>not</strong> added if the

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick condition evaluates to false for the request. Adding the HTTP header

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick to the Vary header of the response is needed for proper caching.</p>

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick <p>It has to be kept in mind that conditions follow a short circuit

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick logic in the case of the '<strong><code>ornext|OR</code></strong>' flag

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick so that certain conditions might not be evaluated at all.</p></li>

1bdd1f8b0e04d77152f52f7cff0480613c6ffd96trawick

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick <li>

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick <code>%{LA-U:variable}</code> can be used for look-aheads which perform

4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick an internal (URL-based) sub-request to determine the final

2509f1cd3be884abbe4852e15b8da00bebaad5b1poirier value of <em>variable</em>. This can be used to access

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf variable for rewriting which is not available at the current

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf stage, but will be set in a later phase.

5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <p>For instance, to rewrite according to the

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <code>REMOTE_USER</code> variable from within the

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung per-server context (<code>httpd.conf</code> file) you must

727872d18412fc021f03969b8641810d8896820bhumbedooh use <code>%{LA-U:REMOTE_USER}</code> - this

0d0ba3a410038e179b695446bb149cce6264e0abnd variable is set by the authorization phases, which come

727872d18412fc021f03969b8641810d8896820bhumbedooh <em>after</em> the URL translation phase (during which mod_rewrite

cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh operates).</p>

0d0ba3a410038e179b695446bb149cce6264e0abnd <p>On the other hand, because mod_rewrite implements

cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh its per-directory context (<code>.htaccess</code> file) via

727872d18412fc021f03969b8641810d8896820bhumbedooh the Fixup phase of the API and because the authorization

0d0ba3a410038e179b695446bb149cce6264e0abnd phases come <em>before</em> this phase, you just can use

0d0ba3a410038e179b695446bb149cce6264e0abnd <code>%{REMOTE_USER}</code> in that context.</p></li>

0d0ba3a410038e179b695446bb149cce6264e0abnd

ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedooh <li>

0d0ba3a410038e179b695446bb149cce6264e0abnd <code>%{LA-F:variable}</code> can be used to perform an internal

0d0ba3a410038e179b695446bb149cce6264e0abnd (filename-based) sub-request, to determine the final value

0d0ba3a410038e179b695446bb149cce6264e0abnd of <em>variable</em>. Most of the time, this is the same as

727872d18412fc021f03969b8641810d8896820bhumbedooh LA-U above.</li>

0d0ba3a410038e179b695446bb149cce6264e0abnd </ol>

0d0ba3a410038e179b695446bb149cce6264e0abnd

30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh <p><em>CondPattern</em> is the condition pattern,

5effc8b39fae5cd169d17f342bfc265705840014rbowen a regular expression which is applied to the

d229f940abfb2490dee17979e9a5ff31b7012eb5rbowen current instance of the <em>TestString</em>.

0d0ba3a410038e179b695446bb149cce6264e0abnd <em>TestString</em> is first evaluated, before being matched against

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd <em>CondPattern</em>.</p>

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd <p><em>CondPattern</em> is usually a

60a4b2c422dcbb08a554fb193105c08da592718bpoirier <em>perl compatible regular expression</em>, but there is

additional syntax available to perform other useful tests against

the <em>Teststring</em>:</p>

<ol>

<li>You can prefix the pattern string with a

'<code>!</code>' character (exclamation mark) to specify a

<strong>non</strong>-matching pattern.</li>

<li>

You can perform lexicographical string comparisons:

<ul>

<li>'<strong>&lt;CondPattern</strong>' (lexicographically

precedes)<br />

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>&gt;CondPattern</strong>' (lexicographically

follows)<br />

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

equal)<br />

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>&lt;=CondPattern</strong>' (lexicographically

less than or equal to)<br />

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>, or is equal to <em>CondPattern</em>

(the two strings are equal, character for character).</li>

<li>'<strong>&gt;=CondPattern</strong>' (lexicographically

greater than or equal to)<br />

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>, or is equal to <em>CondPattern</em>

(the two strings are equal, character for character).</li>

</ul></li>

<li>

You can perform integer comparisons:

<ul>

<li>'<strong>-eq</strong>' (is numerically

<strong>eq</strong>ual to)<br />

The <em>TestString</em> is treated as an integer, and is

numerically compared to the <em>CondPattern</em>. True if

the two are numerically equal.</li>

<li>'<strong>-ge</strong>' (is numerically

<strong>g</strong>reater than or <strong>e</strong>qual to)<br />

The <em>TestString</em> is treated as an integer, and is

numerically compared to the <em>CondPattern</em>. True if

the <em>TestString</em> is numerically greater than or equal

to the <em>CondPattern</em>.</li>

<li>'<strong>-gt</strong>' (is numerically

<strong>g</strong>reater <strong>t</strong>han)<br />

The <em>TestString</em> is treated as an integer, and is

numerically compared to the <em>CondPattern</em>. True if

the <em>TestString</em> is numerically greater than

the <em>CondPattern</em>.</li>

<li>'<strong>-le</strong>' (is numerically

<strong>l</strong>ess than or <strong>e</strong>qual to)<br />

The <em>TestString</em> is treated as an integer, and is

numerically compared to the <em>CondPattern</em>. True if

the <em>TestString</em> is numerically less than or equal

to the <em>CondPattern</em>. Avoid confusion with the

<strong>-l</strong> by using the <strong>-L</strong> or

<strong>-h</strong> variant.</li>

<li>'<strong>-lt</strong>' (is numerically

<strong>l</strong>ess <strong>t</strong>han)<br />

The <em>TestString</em> is treated as an integer, and is

numerically compared to the <em>CondPattern</em>. True if

the <em>TestString</em> is numerically less than

the <em>CondPattern</em>. Avoid confusion with the

<strong>-l</strong> by using the <strong>-L</strong> or

<strong>-h</strong> variant.</li>

</ul>

</li>

<li>You can perform various file attribute tests:

<ul>

<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>-F</strong>' (is existing file, via

subrequest)<br />

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>-H</strong>' (is symbolic link, bash convention)<br />

See <strong>-l</strong>.</li>

<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. May also

use the bash convention of <strong>-L</strong> or

<strong>-h</strong> if there's a possibility of confusion

such as when using the <strong>-lt</strong> or

<strong>-le</strong> tests.</li>

<li>'<strong>-L</strong>' (is symbolic link, bash convention)<br />

See <strong>-l</strong>.</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

than zero.</li>

<li>'<strong>-U</strong>' (is existing URL, via

subrequest)<br />

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>

<li>'<strong>-x</strong>' (has e<strong>x</strong>ecutable

permissions)<br />

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

the underlying OS.</li>

</ul>

<note><title>Note:</title>

All of these tests can

also be prefixed by an exclamation mark ('!') to

negate their meaning.

</note>

</li>

<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

following flags:

<ul>

<li>'<strong><code>nocase|NC</code></strong>'

(<strong>n</strong>o <strong>c</strong>ase)<br />

This makes the test case-insensitive - 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>

<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:

<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...

</pre>

</example>

Without this flag you would have to write the condition/rule

pair three times.

</li>

<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

is well understood.

</li>

</ul>

</li>

</ol>

<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

use the following: </p>

<example>

<pre>

RewriteCond %{HTTP_USER_AGENT} ^Mozilla

RewriteRule ^/$ /homepage.max.html [L]

RewriteCond %{HTTP_USER_AGENT} ^Lynx

RewriteRule ^/$ /homepage.min.html [L]

RewriteRule ^/$ /homepage.std.html [L]

</pre>

</example>

<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

features).

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>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>RewriteRule</name>

<description>Defines rules for the rewriting engine</description>

<syntax>RewriteRule

<em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context></contextlist>

<override>FileInfo</override>

<usage>

<p>The <directive>RewriteRule</directive> 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)

<a href="/directive-dict.html#Syntax">URL-path</a> of the request;

subsequent patterns are applied to the output of the last matched

RewriteRule.</p>

<note><title>What is matched?</title>

<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

<directive module="mod_rewrite">RewriteBase</directive>). 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

<directive module="mod_rewrite">RewriteCond</directive> 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>

</note>

<p>For some hints on <glossary ref="regex">regular

expressions</glossary>, see

the <a href="/rewrite/intro.html#regex">mod_rewrite

Introduction</a>.</p>

<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

default rule.</p>

<note><title>Note</title>

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!

</note>

<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

be a:</p>

<dl>

<dt>file-system path</dt>

<dd>Designates the location on the file-system of the resource

to be delivered to the client.</dd>

<dt>URL-path</dt>

<dd>A <directive

module="core">DocumentRoot</directive>-relative path to the

resource to be served. Note that <module>mod_rewrite</module>

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

<code>/www/file.html</code>, then this will be treated as a

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 <directive

module="mod_alias">Alias</directive>) to be applied to the

resulting URL-path, use the <code>[PT]</code> flag as

described below.</dd>

<dt>Absolute URL</dt>

<dd>If an absolute URL is specified,

<module>mod_rewrite</module> 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

the path.</dd>

</dl>

<p>In addition to plain text, the <em>Substition</em> string can include</p>

<ol>

<li>back-references (<code>$N</code>) to the RewriteRule

pattern</li>

<li>back-references (<code>%N</code>) to the last matched

RewriteCond pattern</li>

<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>

</ol>

<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

they are defined

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>

<note><title>Modifying the Query String</title>

<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>

</note>

<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>

<table border="1">

<tr><th>Flag and syntax</th>

<th>Function</th>

</tr>

<tr>

<td>B</td>

<td>Escape non-alphanumeric characters <em>before</em> applying

the transformation. <em><a

href="/rewrite/flags.html#flag_b">details ...</a></em></td>

</tr>

<tr>

<td>chain|C</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>

</tr>

<tr>

<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>

</tr>

<tr>

<td>discardpathinfo|DPI</td>

<td>Causes the PATH_INFO portion of the rewritten URI to be

discarded. <em><a href="/rewrite/flags.html#flag_dpi">details

...</a></em></td>

</tr>

<tr>

<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> if provided). The form !<em>VAR</em> causes

the environment variable <em>VAR</em> to be unset.<em><a

href="/rewrite/flags.html#flag_e">details ...</a></em></td>

</tr>

<tr>

<td>forbidden|F</td>

<td>Returns a 403 FORBIDDEN response to the client browser.

<em><a href="/rewrite/flags.html#flag_f">details ...</a></em></td>

</tr>

<tr>

<td>gone|G</td>

<td>Returns a 410 GONE response to the client browser. <em><a

href="/rewrite/flags.html#flag_g">details ...</a></em></td>

</tr>

<tr>

<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>

</tr>

<tr>

<td>last|L</td>

<td>Stop the rewriting process immediately and don't apply any

more rules. Especially note caveats for per-directory and

.htaccess context (see also the END flag). <em><a

href="/rewrite/flags.html#flag_l">details ...</a></em></td>

</tr>

<tr>

<td>next|N</td>

<td>Re-run the rewriting process, starting again with the first

rule, using the result of the ruleset so far as a starting

point. <em><a href="/rewrite/flags.html#flag_n">details

...</a></em></td>

</tr>

<tr>

<td>nocase|NC</td>

<td>Makes the pattern pattern comparison case-insensitive.

<em><a href="/rewrite/flags.html#flag_nc">details ...</a></em></td>

</tr>

<tr>

<td>noescape|NE</td>

<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>

</tr>

<tr>

<td>nosubreq|NS</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>

</tr>

<tr>

<td>proxy|P</td>

<td>Force the substitution URL to be internally sent as a proxy

request. <em><a href="/rewrite/flags.html#flag_p">details

...</a></em></td>

</tr>

<tr>

<td>passthrough|PT</td>

<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>

</tr>

<tr>

<td>qsappend|QSA</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>

</tr>

<tr>

<td>qsdiscard|QSD</td>

<td>Discard any query string attached to the incoming URI.

<em><a href="/rewrite/flags.html#flag_qsd">details

...</a></em></td>

</tr>

<tr>

<td>redirect|R[=<em>code</em>]</td>

<td>Forces an external redirect, optionally with the specified

HTTP status code. <em><a

href="/rewrite/flags.html#flag_r">details ...</a></em>

</td>

</tr>

<tr>

<td>END</td>

<td>Stop the rewriting process immediately and don't apply any

more rules. Also prevents further execution of rewrite rules

in per-directory and .htaccess context. (Available in 2.3.9 and later)

<em><a href="/rewrite/flags.html#flag_l">details ...</a></em></td>

</tr>

<tr>

<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>

</tr>

<tr>

<td>tyle|T=<em>MIME-type</em></td>

<td>Force the <glossary>MIME-type</glossary> of the target file

to be the specified type. <em><a

href="/rewrite/flags.html#flag_t">details ...</a></em></td>

</tr>

</table>

<note><title>Home directory expansion</title>

<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

of <module>mod_userdir</module>.</p>

<p> This expansion does not occur when the <em>PT</em>

flag is used on the <directive module="mod_rewrite">RewriteRule</directive>

directive.</p>

</note>

<note><title>Per-directory Rewrites</title>

<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

<directive module="mod_rewrite">RewriteBase</directive> directive for

more information.</p>

<p>The rewrite engine may also be used in <directive type="section"

module="core">Directory</directive> 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 <directive type="section"

module="core">Directory</directive> section.</p>

<p>Although rewrite rules are syntactically permitted in <directive

type="section" module="core">Location</directive> and <directive

type="section" module="core">Files</directive> sections, this

should never be necessary and is unsupported.</p>

</note>

<p>Here are all possible substitution combinations and their

meanings:</p>

<p><strong>Inside per-server configuration

(<code>httpd.conf</code>)<br />

for request ``<code>GET

/somepath/pathinfo</code>'':</strong><br />

</p>

<table border="1">

<tr>

<th>Given Rule</th>

<th>Resulting Substitution</th>

</tr>

<tr>

<td>^/somepath(.*) otherpath$1</td>

<td>invalid, not supported</td>

</tr>

<tr>

<td>^/somepath(.*) otherpath$1 [R]</td>

<td>invalid, not supported</td>

</tr>

<tr>

<td>^/somepath(.*) otherpath$1 [P]</td>

<td>invalid, not supported</td>

</tr>

<tr>

<td>^/somepath(.*) /otherpath$1</td>

<td>/otherpath/pathinfo</td>

</tr>

<tr>

<td>^/somepath(.*) /otherpath$1 [R]</td>

<td>http://thishost/otherpath/pathinfo via external redirection</td>

</tr>

<tr>

<td>^/somepath(.*) /otherpath$1 [P]</td>

<td>doesn't make sense, not supported</td>

</tr>

<tr>

<td>^/somepath(.*) http://thishost/otherpath$1</td>

<td>/otherpath/pathinfo</td>

</tr>

<tr>

<td>^/somepath(.*) http://thishost/otherpath$1 [R]</td>

<td>http://thishost/otherpath/pathinfo via external redirection</td>

</tr>

<tr>

<td>^/somepath(.*) http://thishost/otherpath$1 [P]</td>

<td>doesn't make sense, not supported</td>

</tr>

<tr>

<td>^/somepath(.*) http://otherhost/otherpath$1</td>

<td>http://otherhost/otherpath/pathinfo via external redirection</td>

</tr>

<tr>

<td>^/somepath(.*) http://otherhost/otherpath$1 [R]</td>

<td>http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant)</td>

</tr>

<tr>

<td>^/somepath(.*) http://otherhost/otherpath$1 [P]</td>

<td>http://otherhost/otherpath/pathinfo via internal proxy</td>

</tr>

</table>

<p><strong>Inside per-directory configuration for

<code>/somepath</code><br />

(<code>/physical/path/to/somepath/.htacccess</code>, with

<code>RewriteBase /somepath</code>)<br />

for request ``<code>GET

/somepath/localpath/pathinfo</code>'':</strong><br />

</p>

<table border="1">

<tr>

<th>Given Rule</th>

<th>Resulting Substitution</th>

</tr>

<tr>

<td>^localpath(.*) otherpath$1</td>

<td>/somepath/otherpath/pathinfo</td>

</tr>

<tr>

<td>^localpath(.*) otherpath$1 [R]</td>

<td>http://thishost/somepath/otherpath/pathinfo via external

redirection</td>

</tr>

<tr>

<td>^localpath(.*) otherpath$1 [P]</td>

<td>doesn't make sense, not supported</td>

</tr>

<tr>

<td>^localpath(.*) /otherpath$1</td>

<td>/otherpath/pathinfo</td>

</tr>

<tr>

<td>^localpath(.*) /otherpath$1 [R]</td>

<td>http://thishost/otherpath/pathinfo via external redirection</td>

</tr>

<tr>

<td>^localpath(.*) /otherpath$1 [P]</td>

<td>doesn't make sense, not supported</td>

</tr>

<tr>

<td>^localpath(.*) http://thishost/otherpath$1</td>

<td>/otherpath/pathinfo</td>

</tr>

<tr>

<td>^localpath(.*) http://thishost/otherpath$1 [R]</td>

<td>http://thishost/otherpath/pathinfo via external redirection</td>

</tr>

<tr>

<td>^localpath(.*) http://thishost/otherpath$1 [P]</td>

<td>doesn't make sense, not supported</td>

</tr>

<tr>

<td>^localpath(.*) http://otherhost/otherpath$1</td>

<td>http://otherhost/otherpath/pathinfo via external redirection</td>

</tr>

<tr>

<td>^localpath(.*) http://otherhost/otherpath$1 [R]</td>

<td>http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant)</td>

</tr>

<tr>

<td>^localpath(.*) http://otherhost/otherpath$1 [P]</td>

<td>http://otherhost/otherpath/pathinfo via internal proxy</td>

</tr>

</table>

</usage>

</directivesynopsis>

</modulesynopsis>