mirror of
https://github.com/apache/httpd.git
synced 2025-11-08 04:22:21 +03:00
5848a42169
counterintuitively in per-directory context. (lots of mysterious no-op rulesets due to ^/ in htaccess) Tweak QSA text. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@832914 13f79535-47bb-0310-9956-ffa450edef68
1553 lines
65 KiB
XML
1553 lines
65 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<modulesynopsis metafile="mod_rewrite.xml.meta">
|
|
|
|
<name>mod_rewrite</name>
|
|
|
|
<description>Provides a rule-based rewriting engine to rewrite requested
|
|
URLs on the fly</description>
|
|
|
|
<status>Extension</status>
|
|
<sourcefile>mod_rewrite.c</sourcefile>
|
|
<identifier>rewrite_module</identifier>
|
|
<compatibility>Available in Apache 1.3 and later</compatibility>
|
|
|
|
<summary>
|
|
<p>The <module>mod_rewrite</module> module uses a rule-based rewriting
|
|
engine, based on a regular-expression parser, to rewrite requested URLs on
|
|
the fly. By default, <module>mod_rewrite</module> maps a URL to a filesystem
|
|
path. However, it can also be used to redirect one URL to another URL, or
|
|
to invoke an internal proxy fetch.</p>
|
|
<p><module>mod_rewrite</module> provides a flexible and powerful way to
|
|
manipulate URLs using an unlimited number of rules. Each rule can have an
|
|
unlimited number of attached rule conditions, to allow you to rewrite URL
|
|
based on server variables, environment variables, HTTP headers, or time
|
|
stamps.</p>
|
|
<p><module>mod_rewrite</module> operates on the full URL path, including the
|
|
path-info section. A rewrite rule can be invoked in
|
|
<code>httpd.conf</code> or in <code>.htaccess</code>. The path generated
|
|
by a rewrite rule can include a query string, or can lead to internal
|
|
sub-processing, external request redirection, or internal proxy
|
|
throughput.</p>
|
|
|
|
<p>Further details, discussion, and examples, are provided in the
|
|
<a href="../rewrite/">detailed mod_rewrite documentation</a>.</p>
|
|
</summary>
|
|
|
|
|
|
<directivesynopsis>
|
|
<name>RewriteEngine</name>
|
|
<description>Enables or disables runtime rewriting engine</description>
|
|
<syntax>RewriteEngine on|off</syntax>
|
|
<default>RewriteEngine off</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context></contextlist>
|
|
<override>FileInfo</override>
|
|
|
|
<usage>
|
|
|
|
<p>The <directive>RewriteEngine</directive> 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 <directive
|
|
module="mod_rewrite">RewriteRule</directive> 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><directive>RewriteMap</directive> directives of the type <code>prg</code>
|
|
are not started during server initialization if they're defined in a
|
|
context that does not have <directive>RewriteEngine</directive> set to
|
|
<code>on</code></p>
|
|
</usage>
|
|
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RewriteOptions</name>
|
|
<description>Sets some special options for the rewrite engine</description>
|
|
<syntax>RewriteOptions <var>Options</var></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context></contextlist>
|
|
<override>FileInfo</override>
|
|
<compatibility><code>MaxRedirects</code> is no longer available in version 2.1 and
|
|
later</compatibility>
|
|
<usage>
|
|
|
|
<p>The <directive>RewriteOptions</directive> 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>
|
|
|
|
<dl>
|
|
<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
|
|
<directive type="section" module="core">Directory</directive>
|
|
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
|
|
be processed.</dd>
|
|
</dl>
|
|
</usage>
|
|
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RewriteLog</name>
|
|
<description>Sets the name of the file used for logging rewrite engine
|
|
processing</description>
|
|
<syntax>RewriteLog <em>file-path</em></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>RewriteLog</directive> 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
|
|
server config.</p>
|
|
|
|
<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 <directive>RewriteLog</directive>
|
|
directive or use <code>RewriteLogLevel 0</code>!
|
|
</note>
|
|
|
|
<note type="securitywarning"><title>Security</title>
|
|
|
|
See the <a href="../misc/security_tips.html">Apache Security Tips</a>
|
|
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.
|
|
</note>
|
|
|
|
<example><title>Example</title>
|
|
RewriteLog "/usr/local/var/apache/logs/rewrite.log"
|
|
</example>
|
|
|
|
</usage>
|
|
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RewriteLogLevel</name>
|
|
<description>Sets the verbosity of the log file used by the rewrite
|
|
engine</description>
|
|
<syntax>RewriteLogLevel <em>Level</em></syntax>
|
|
<default>RewriteLogLevel 0</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>RewriteLogLevel</directive> directive sets the
|
|
verbosity level of the rewriting logfile. The default level 0
|
|
means no logging, while 9 or more means that practically all
|
|
actions are logged.</p>
|
|
|
|
<p>To disable the logging of rewriting actions simply set
|
|
<em>Level</em> to 0. This disables all rewrite action
|
|
logs.</p>
|
|
|
|
<note> Using a high value for
|
|
<em>Level</em> will slow down your Apache server
|
|
dramatically! Use the rewriting logfile at a
|
|
<em>Level</em> greater than 2 only for debugging!
|
|
</note>
|
|
|
|
<example><title>Example</title>
|
|
RewriteLogLevel 3
|
|
</example>
|
|
|
|
</usage>
|
|
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RewriteLock</name>
|
|
<description>Sets the name of the lock file used for <directive
|
|
module="mod_rewrite">RewriteMap</directive>
|
|
synchronization</description>
|
|
<syntax>RewriteLock <em>file-path</em></syntax>
|
|
<contextlist><context>server config</context></contextlist>
|
|
|
|
<usage>
|
|
<p>This directive sets the filename for a synchronization
|
|
lockfile which mod_rewrite needs to communicate with <directive
|
|
module="mod_rewrite">RewriteMap</directive>
|
|
<em>programs</em>. Set this lockfile to a local path (not on a
|
|
NFS-mounted device) when you want to use a rewriting
|
|
map-program. It is not required for other types of rewriting
|
|
maps.</p>
|
|
</usage>
|
|
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RewriteMap</name>
|
|
<description>Defines a mapping function for key-lookup</description>
|
|
<syntax>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
|
|
</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
<compatibility>The choice of different dbm types is available in
|
|
Apache 2.0.41 and later</compatibility>
|
|
|
|
<usage>
|
|
<p>The <directive>RewriteMap</directive> directive defines a
|
|
<em>Rewriting Map</em> which can be used inside rule
|
|
substitution strings by the mapping-functions to
|
|
insert/substitute fields through a key lookup. The source of
|
|
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>
|
|
|
|
<p class="indent">
|
|
<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>
|
|
<code>}</code></strong>
|
|
</p>
|
|
|
|
<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
|
|
<directive>RewriteMap</directive> as:</p>
|
|
|
|
<example>
|
|
RewriteMap examplemap txt:/path/to/file/map.txt
|
|
</example>
|
|
|
|
<p>You would then be able to use this map in a
|
|
<directive>RewriteRule</directive> as follows:</p>
|
|
|
|
<example>
|
|
RewriteRule ^/ex/(.*) ${examplemap:$1}
|
|
</example>
|
|
|
|
<p>The following combinations for <em>MapType</em> and
|
|
<em>MapSource</em> can be used:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<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
|
|
line.</p>
|
|
|
|
<p class="indent">
|
|
<strong><em>MatchingKey</em>
|
|
<em>SubstValue</em></strong>
|
|
</p>
|
|
|
|
<example><title>Example</title>
|
|
<pre>
|
|
##
|
|
## map.txt -- rewriting map
|
|
##
|
|
|
|
Ralf.S.Engelschall rse # Bastard Operator From Hell
|
|
Mr.Joe.Average joe # Mr. Average
|
|
</pre>
|
|
</example>
|
|
|
|
<example>
|
|
RewriteMap real-to-user txt:/path/to/file/map.txt
|
|
</example>
|
|
</li>
|
|
|
|
<li>
|
|
<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>
|
|
<p>Example:</p>
|
|
|
|
<example><title>Rewrite map file</title>
|
|
<pre>
|
|
##
|
|
## map.txt -- rewriting map
|
|
##
|
|
|
|
static www1|www2|www3|www4
|
|
dynamic www5|www6
|
|
</pre>
|
|
</example>
|
|
|
|
<example><title>Configuration directives</title>
|
|
RewriteMap servers rnd:/path/to/file/map.txt<br />
|
|
<br />
|
|
RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
|
|
[NC,P,L]<br />
|
|
RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
|
|
</example>
|
|
</li>
|
|
|
|
<li>
|
|
<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
|
|
db depending on <a href="../install.html#dbm">compile-time
|
|
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>
|
|
|
|
<example>
|
|
$ httxt2dbm -i mapfile.txt -o mapfile.map
|
|
</example>
|
|
</li>
|
|
|
|
<li>
|
|
<strong>Internal Function</strong><br />
|
|
MapType: <code>int</code>, MapSource: Internal Apache
|
|
function
|
|
|
|
<p>Here, the source is an internal Apache function.
|
|
Currently you cannot create your own, but the following
|
|
functions already exist:</p>
|
|
|
|
<ul>
|
|
<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
|
|
hex-encodings.</li>
|
|
|
|
<li><strong>unescape</strong>:<br />
|
|
Translates hex-encodings in the key back to
|
|
special characters.</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<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
|
|
'<code>#!/path/to/interpreter</code>' as the first
|
|
line).</p>
|
|
|
|
<p>This program is started once, when the Apache 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>External rewriting programs are not started if they're defined in a
|
|
context that does not have <directive>RewriteEngine</directive> set to
|
|
<code>on</code></p>.
|
|
|
|
<p>A trivial program which will implement a 1:1 map (<em>i.e.</em>,
|
|
key == value) could be:</p>
|
|
|
|
<example>
|
|
<pre>
|
|
#!/usr/bin/perl
|
|
$| = 1;
|
|
while (<STDIN>) {
|
|
# ...put here any transformations or lookups...
|
|
print $_;
|
|
}
|
|
</pre>
|
|
</example>
|
|
|
|
<p>But be very careful:</p>
|
|
|
|
<ol>
|
|
<li>``<em>Keep it simple, stupid</em>'' (KISS).
|
|
If this program hangs, it will cause Apache 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>
|
|
|
|
<li>The <directive
|
|
module="mod_rewrite">RewriteLock</directive> directive can
|
|
be used to define a lockfile which mod_rewrite can use to synchronize
|
|
communication with the mapping program. By default no such
|
|
synchronization takes place.</li>
|
|
</ol>
|
|
</li>
|
|
<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 <module>mod_dbd</module> 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
|
|
restart.</p>
|
|
<p>If a query returns more than one row, a random row from
|
|
the result set is used.</p>
|
|
<example>
|
|
<title>Example</title>
|
|
RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
|
|
</example>
|
|
</li>
|
|
</ul>
|
|
<p>The <directive>RewriteMap</directive> directive can occur more than
|
|
once. For each mapping-function use one
|
|
<directive>RewriteMap</directive> 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>
|
|
|
|
<note><title>Note</title> 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
|
|
once!
|
|
</note>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RewriteBase</name>
|
|
<description>Sets the base URL for per-directory rewrites</description>
|
|
<syntax>RewriteBase <em>URL-path</em></syntax>
|
|
<default>None</default>
|
|
<contextlist><context>directory</context><context>.htaccess</context>
|
|
</contextlist>
|
|
<override>FileInfo</override>
|
|
|
|
<usage>
|
|
<p>The <directive>RewriteBase</directive> directive explicitly
|
|
sets the base URL for per-directory rewrites.
|
|
When you use a <directive module="mod_rewrite">RewriteRule</directive>
|
|
in a <code>.htaccess</code> file, <module>mod_rewrite</module> strips off
|
|
the local directory prefix before processing, then rewrites the rest of
|
|
the URL. When the rewrite is completed, <module>mod_rewrite</module>
|
|
automatically adds the local directory prefix back on to the path.</p>
|
|
|
|
<p>If your URL path does not exist on the filesystem,
|
|
you must use <directive>RewriteBase</directive> in every
|
|
<code>.htaccess</code> file where you want to use <directive
|
|
module="mod_rewrite">RewriteRule</directive> directives. </p>
|
|
|
|
<p>The example below demonstrates how to map
|
|
<code>http://example.com/foo/index.html</code> to
|
|
<code>/home/www/example/newsite.html</code>, in a <code>.htaccess</code>
|
|
file. This assumes that the content available at
|
|
<code>http://example.com/</code> is on disk at
|
|
<code>/home/www/example/</code>.</p>
|
|
<example>
|
|
<pre>
|
|
RewriteEngine On
|
|
RewriteBase /foo/
|
|
RewriteRule ^index\.html$ newsite.html
|
|
</pre>
|
|
</example>
|
|
|
|
</usage>
|
|
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>RewriteCond</name>
|
|
<description>Defines a condition under which rewriting will take place
|
|
</description>
|
|
<syntax> RewriteCond
|
|
<em>TestString</em> <em>CondPattern</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 module="mod_rewrite">RewriteCond</directive>
|
|
directive defines a rule condition. One or more <directive
|
|
module="mod_rewrite">RewriteCond</directive>
|
|
conditions can precede a <directive module="mod_rewrite"
|
|
>RewriteRule</directive> directive. The following rewrite rule is then
|
|
used only if these conditions are met, and if the URI matches the pattern
|
|
specified in the rule.</p>
|
|
|
|
<section id="TestString">
|
|
<title>TestString</title>
|
|
<p><code><em>TestString</em></code> can contain plain text, any of the
|
|
following expanded constructs, or both.</p>
|
|
<ul>
|
|
<li>
|
|
<strong>RewriteRule backreferences</strong>: These are
|
|
backreferences of the form <strong><code>$N</code></strong>
|
|
(1 <= N <= 9). They provide access to the grouped
|
|
parts of the current <code>RewriteRule</code> pattern. The grouped
|
|
parts of the pattern are those in parentheses.</li>
|
|
<li>
|
|
<strong>RewriteCond backreferences</strong>: These are
|
|
backreferences of the form <strong><code>%N</code></strong>
|
|
(1 <= N <= 9). They provide access to the grouped
|
|
parts of the last-matched <code>RewriteCond</code> pattern. The
|
|
grouped parts of the pattern are those in parentheses.</li>
|
|
<li>
|
|
<strong>RewriteMap expansions</strong>: These are
|
|
expansions of the form <strong><code
|
|
>${mapname:key|default}</code></strong>.
|
|
See the <a href="#mapfunc">RewriteMap documentation</a>
|
|
for more details.
|
|
</li>
|
|
<li>
|
|
<strong>Server variables</strong>: These are variables of
|
|
the form
|
|
<strong><code>%{ <em>NAME_OF_VARIABLE</em> }</code></strong>,
|
|
where <em>NAME_OF_VARIABLE</em> is one of the server variables from
|
|
the table below:
|
|
|
|
<table>
|
|
<columnspec><column width=".3"/><column width=".3"/>
|
|
<column width=".3"/></columnspec>
|
|
<tr>
|
|
<th>HTTP headers:</th> <th>connection & request:</th> <th></th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
HTTP_USER_AGENT<br />
|
|
HTTP_REFERER<br />
|
|
HTTP_COOKIE<br />
|
|
HTTP_FORWARDED<br />
|
|
HTTP_HOST<br />
|
|
HTTP_PROXY_CONNECTION<br />
|
|
HTTP_ACCEPT<br />
|
|
</td>
|
|
|
|
<td>
|
|
REMOTE_ADDR<br />
|
|
REMOTE_HOST<br />
|
|
REMOTE_PORT<br />
|
|
REMOTE_USER<br />
|
|
REMOTE_IDENT<br />
|
|
REQUEST_METHOD<br />
|
|
SCRIPT_FILENAME<br />
|
|
PATH_INFO<br />
|
|
QUERY_STRING<br />
|
|
AUTH_TYPE<br />
|
|
</td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th>server internals:</th> <th>date and time:</th> <th>specials:</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
DOCUMENT_ROOT<br />
|
|
SERVER_ADMIN<br />
|
|
SERVER_NAME<br />
|
|
SERVER_ADDR<br />
|
|
SERVER_PORT<br />
|
|
SERVER_PROTOCOL<br />
|
|
SERVER_SOFTWARE<br />
|
|
</td>
|
|
|
|
<td>
|
|
TIME_YEAR<br />
|
|
TIME_MON<br />
|
|
TIME_DAY<br />
|
|
TIME_HOUR<br />
|
|
TIME_MIN<br />
|
|
TIME_SEC<br />
|
|
TIME_WDAY<br />
|
|
TIME<br />
|
|
</td>
|
|
|
|
<td>
|
|
API_VERSION<br />
|
|
THE_REQUEST<br />
|
|
REQUEST_URI<br />
|
|
REQUEST_FILENAME<br />
|
|
IS_SUBREQ<br />
|
|
HTTPS<br />
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</li></ul>
|
|
<note><p>The following variables are specific to
|
|
<module>mod_rewrite</module>:</p>
|
|
<dl>
|
|
<dt><code>IS_SUBREQ</code></dt>
|
|
|
|
<dd>Contains the text "true" if the request
|
|
currently being processed is a sub-request, or
|
|
"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>The version of the Apache module API contained in the
|
|
current httpd build, as defined in
|
|
include/ap_mmn.h.</dd>
|
|
|
|
<dt><code>THE_REQUEST</code></dt>
|
|
|
|
<dd>The full HTTP request line sent by the
|
|
browser to the server (e.g., "<code>GET
|
|
/index.html HTTP/1.1</code>"). This does not
|
|
include any additional headers sent by the
|
|
browser.</dd>
|
|
|
|
<dt><code>REQUEST_URI</code></dt>
|
|
|
|
<dd>The resource requested in the HTTP request
|
|
line.</dd>
|
|
|
|
<dt><code>REQUEST_FILENAME</code></dt>
|
|
|
|
<dd>The full local filesystem path of the file or
|
|
script matching the request.</dd>
|
|
|
|
<dt><code>HTTPS</code></dt>
|
|
|
|
<dd>Contains the text "on" if the connection is
|
|
using SSL/TLS, or "off" otherwise. This variable
|
|
does not depend on <module>mod_ssl</module> being loaded.</dd>
|
|
|
|
</dl>
|
|
</note>
|
|
|
|
<p>Note that the <code>SCRIPT_FILENAME</code> and
|
|
<code>REQUEST_FILENAME</code>
|
|
variables both contain the value of the
|
|
<code>filename</code> field of the internal
|
|
<code>request_rec</code> structure.
|
|
If a substitution occurs and rewriting continues,
|
|
the value of both variables will be updated accordingly.
|
|
In a per-server context, before the
|
|
request is mapped to the filesystem, these variables contain the value
|
|
of <code>REQUEST_URI</code>, because the full filesystem path is not
|
|
yet known. To obtain the full filesystem
|
|
path of a request in a per-server context, use a URL-based
|
|
look-ahead <code>%{LA-U:REQUEST_FILENAME}</code> to determine
|
|
the final value of <code>REQUEST_FILENAME</code>.</p>
|
|
|
|
<p>Other available variables include the following:</p>
|
|
<ul><li>
|
|
<code>%{ENV:<em>variable</em>}</code>, where <em>variable</em> can be
|
|
any environment variable.</li>
|
|
|
|
<li>
|
|
<code>%{SSL:<em>variable</em>}</code>, where <em>variable</em> is the
|
|
name of an <a href="mod_ssl.html#envvars">SSL environment
|
|
variable</a>. If <module>mod_ssl</module> is not loaded, this
|
|
will always expand to the empty string.</li>
|
|
<li>
|
|
<code>%{HTTP:<em>header</em>}</code>, where <em>header</em> can be
|
|
any HTTP MIME-header name. For example,
|
|
<code>%{HTTP:Proxy-Connection}</code> is the value of the HTTP header
|
|
``<code>Proxy-Connection:</code>''. If a HTTP header is used in a
|
|
condition, and the condition evaluates to <code>true</code>, then that
|
|
header is added to the Vary header of the response. This is used to
|
|
ensure proper caching.
|
|
If a previous condition has evaluated to <code>true</code> and the
|
|
'<strong><code>ornext|OR</code></strong>' flag is in use, later
|
|
conditions are not evaluated, and therefore headers are not added to the
|
|
Vary header.</li>
|
|
<li>
|
|
<code>%{LA-U:<em>variable</em>}</code>, which is used to perform
|
|
an internal URL-based sub-request, to determine the final
|
|
value of <em>variable</em>. This can be used to access the value of
|
|
a variable which is to be set in a later phase. For example, the
|
|
<code>REMOTE_USER</code> variable is set in the authorization phase of
|
|
processing. This comes after the URL translation phase, where rewrite
|
|
rules in <code>httpd.conf</code> are applied, but before the fixup
|
|
phase, where rewrite rules in a <code>.htaccess</code> file are applied.
|
|
Therefore, to obtain the value of the <code>REMOTE_USER</code> variable
|
|
within <code>httpd.conf</code>, you must use <code
|
|
>%{LA-U:REMOTE_USER}</code>. To obtain the value of the
|
|
<code>REMOTE_USER</code> variable within a <code>.htaccess</code> file,
|
|
simply use <code>%{REMOTE_USER}</code></li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section id="CondPattern">
|
|
<title>CondPattern</title>
|
|
<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
|
|
additions:</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>
|
|
There are some special variants of <em>CondPatterns</em>.
|
|
Instead of real regular expression strings you can also
|
|
use one of the following:
|
|
|
|
<ul>
|
|
<li>'<strong><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>>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>-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
|
|
than zero.</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.</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>
|
|
|
|
<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>-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>
|
|
</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>
|
|
|
|
</section>
|
|
</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 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 following flags: </p>
|
|
|
|
<dl>
|
|
<dt>'<code>B</code>' (escape backreferences)</dt>
|
|
<dd><p>Apache has to unescape URLs before mapping them,
|
|
so backreferences will be unescaped at the time they are applied.
|
|
Using the B flag, non-alphanumeric characters in backreferences
|
|
will be escaped. For example, consider the rule:</p>
|
|
<example>
|
|
RewriteRule ^(/.*)$ /index.php?show=$1
|
|
</example>
|
|
<p>This will map <code>/C++</code> to
|
|
<code>/index.php?show=/C++</code>. But it will also map
|
|
<code>/C%2b%2b</code> to <code>/index.php?show=/C++</code>, because
|
|
the <code>%2b</code> has been unescaped. With the B flag, it will
|
|
instead map to <code>/index.php?show=/C%2b%2b</code>.</p>
|
|
<p>This escaping is particularly necessary in a proxy situation,
|
|
when the backend may break if presented with an unescaped URL.</p>
|
|
</dd>
|
|
|
|
<dt>'<code>chain|C</code>'
|
|
(chained with next rule)</dt><dd>
|
|
This flag chains the current rule with the next rule
|
|
(which itself can be chained with the following rule,
|
|
and so on). This has the following effect: if a rule
|
|
matches, then processing continues as usual -
|
|
the flag has no effect. If the rule does
|
|
<strong>not</strong> match, then all following chained
|
|
rules are skipped. For instance, it can be used to remove the
|
|
``<code>.www</code>'' part, inside a per-directory rule set,
|
|
when you let an external redirect happen (where the
|
|
``<code>.www</code>'' part should not occur!).</dd>
|
|
|
|
<dt>'<code>cookie|CO=</code><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>[:<em>secure</em>[:<em>httponly</em>]]]]'
|
|
(set cookie)</dt><dd>
|
|
This sets a cookie in the client's browser. The cookie's name
|
|
is specified by <em>NAME</em> and the value is
|
|
<em>VAL</em>. The <em>domain</em> field is the domain of the
|
|
cookie, such as '.apache.org', the optional <em>lifetime</em>
|
|
is the lifetime of the cookie in minutes (0 means expires at end
|
|
of session), and the optional
|
|
<em>path</em> is the path of the cookie. If <em>secure</em>
|
|
is set to 'secure', 'true' or '1', the cookie is only transmitted via secured
|
|
connections. If <em>httponly</em> is set to 'HttpOnly', 'true' or '1', the
|
|
<code>HttpOnly</code> flag is used, making the cookie inaccessible
|
|
to JavaScript code on browsers that support this feature.</dd>
|
|
|
|
<dt>'<code>discardpathinfo|DPI'
|
|
(discard PATH_INFO)</code></dt><dd>
|
|
<p>This flag is available from 2.2.12</p>
|
|
<p>In per-directory context, the URI each <directive>RewriteRule</directive>
|
|
compares against is the concatenation of the current values of the URI
|
|
and PATH_INFO.</p>
|
|
|
|
<p>The current URI can be the initial URI as requested by the client, the
|
|
result of a previous round of mod_rewrite processing, or the result of
|
|
a prior rule in the current round of mod_rewrite processing.</p>
|
|
|
|
<p>In contrast, the PATH_INFO that is appended to the URI before each
|
|
rule reflects only the value of PATH_INFO before this round of
|
|
mod_rewrite processing. As a consequence, if large portions
|
|
of the URI are matched and copied into a substitution in multiple
|
|
<directive>RewriteRule</directive> directives, without regard for
|
|
which parts of the URI came from the current PATH_INFO, the final
|
|
URI may have multiple copies of PATH_INFO appended to it.</p>
|
|
|
|
<p>Use this flag on any substitution where the PATH_INFO that resulted
|
|
from the previous mapping of this request to the filesystem is not of
|
|
interest. This flag permanently forgets the PATH_INFO established
|
|
before this round of mod_rewrite processing began. PATH_INFO will
|
|
not be recalculated until the current round of mod_rewrite processing
|
|
completes. Subsequent rules during this round of processing will see
|
|
only the direct result of substitutions, without any PATH_INFO
|
|
appended.</p></dd>
|
|
|
|
<dt>
|
|
'<code>env|E=</code><em>VAR</em>:<em>VAL</em>'
|
|
(set environment variable)</dt><dd>
|
|
This forces an environment variable named <em>VAR</em> to
|
|
be set to the value <em>VAL</em>, where <em>VAL</em> can
|
|
contain regexp backreferences (<code>$N</code> and
|
|
<code>%N</code>) which will be expanded. You can use this
|
|
flag more than once, to set more than one variable. The
|
|
variables can later be dereferenced in many situations, most commonly
|
|
from within XSSI (via <code><!--#echo
|
|
var="VAR"--></code>) or CGI (<code>$ENV{'VAR'}</code>).
|
|
You can also dereference the variable in a later RewriteCond pattern, using
|
|
<code>%{ENV:VAR}</code>. Use this to strip
|
|
information from URLs, while maintaining a record of that information.</dd>
|
|
|
|
<dt>'<code>forbidden|F</code>' (force URL
|
|
to be forbidden)</dt><dd>
|
|
This forces the current URL to be forbidden - it immediately
|
|
sends back a HTTP response of 403 (FORBIDDEN).
|
|
Use this flag in conjunction with
|
|
appropriate RewriteConds to conditionally block some
|
|
URLs.</dd>
|
|
|
|
<dt>'<code>gone|G</code>' (force URL to be
|
|
gone)</dt><dd>
|
|
This forces the current URL to be gone - it
|
|
immediately sends back a HTTP response of 410 (GONE). Use
|
|
this flag to mark pages which no longer exist as gone.</dd>
|
|
|
|
<dt>
|
|
'<code>handler|H</code>=<em>Content-handler</em>'
|
|
(force Content handler)</dt><dd>
|
|
Force the Content-handler of the target file to be
|
|
<em>Content-handler</em>. For instance, this can be used to
|
|
simulate the <module>mod_alias</module> directive
|
|
<directive module="mod_alias">ScriptAlias</directive>,
|
|
which internally forces all files
|
|
inside the mapped directory to have a handler of
|
|
``<code>cgi-script</code>''.<br />
|
|
If used in per-directory context, there must not be a substitution
|
|
which changes the path. Use this flag in per-directory context only
|
|
with <code>-</code> (dash) as the substitution, otherwise the request
|
|
will fail.</dd>
|
|
|
|
<dt>'<code>last|L</code>'
|
|
(last rule)</dt><dd> Stop the rewriting process
|
|
here and don't apply any more rewrite rules. This corresponds
|
|
to the Perl <code>last</code> command or the
|
|
<code>break</code> command in C. Use this flag to prevent the
|
|
currently rewritten URL from being rewritten further by
|
|
following rules. Remember, however, that if the
|
|
<directive>RewriteRule</directive> generates an internal
|
|
redirect (which frequently occurs when rewriting in a
|
|
per-directory context), this will reinject the request and
|
|
will cause processing to be repeated starting from the first
|
|
<directive>RewriteRule</directive>.</dd>
|
|
|
|
<dt>'<code>next|N</code>'
|
|
(next round)</dt><dd>
|
|
Re-run the rewriting process (starting again with the
|
|
first rewriting rule). This time, the URL to match is no longer
|
|
the original URL, but rather the URL returned by the last rewriting rule.
|
|
This corresponds to the Perl <code>next</code> command or
|
|
the <code>continue</code> command in C. Use
|
|
this flag to restart the rewriting process -
|
|
to immediately go to the top of the loop.
|
|
<strong>Be careful not to create an infinite
|
|
loop!</strong></dd>
|
|
|
|
<dt>'<code>nocase|NC</code>'
|
|
(no case)</dt><dd>
|
|
This makes the <em>Pattern</em> case-insensitive,
|
|
ignoring difference between 'A-Z' and
|
|
'a-z' when <em>Pattern</em> is matched against the current
|
|
URL.</dd>
|
|
|
|
<dt>
|
|
'<code>noescape|NE</code>'
|
|
(no URI escaping of
|
|
output)</dt><dd>
|
|
This flag prevents mod_rewrite from applying the usual URI
|
|
escaping rules to the result of a rewrite. Ordinarily,
|
|
special characters (such as '%', '$', ';', and so on)
|
|
will be escaped into their hexcode equivalents ('%25',
|
|
'%24', and '%3B', respectively); this flag prevents this
|
|
from happening. This allows percent symbols to appear in
|
|
the output, as in
|
|
<example>
|
|
RewriteRule ^/foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
|
|
</example>
|
|
which would turn '<code>/foo/zed</code>' into a safe
|
|
request for '<code>/bar?arg=P1=zed</code>'.
|
|
</dd>
|
|
|
|
<dt>
|
|
'<code>nosubreq|NS</code>'
|
|
(not for internal
|
|
sub-requests)</dt><dd>
|
|
<p>This flag forces the rewriting engine to skip a
|
|
rewriting rule if the current request is an internal
|
|
sub-request. For instance, sub-requests occur internally
|
|
in Apache when <module>mod_dir</module> tries to find out
|
|
information about possible directory default files
|
|
(<code>index.xxx</code> files). On sub-requests it is not
|
|
always useful, and can even cause errors, if
|
|
the complete set of rules are applied. Use this flag to
|
|
exclude some rules.</p>
|
|
<p>To decide whether or not to use this rule: if you
|
|
prefix URLs with CGI-scripts, to force them to be
|
|
processed by the CGI-script, it's likely that you
|
|
will run into problems (or significant overhead) on
|
|
sub-requests. In these cases, use this flag.</p>
|
|
</dd>
|
|
|
|
<dt>
|
|
'<code>proxy|P</code>' (force
|
|
proxy)</dt><dd>
|
|
This flag forces the substitution part to be internally
|
|
sent as a proxy request and immediately (rewrite
|
|
processing stops here) put through the <a
|
|
href="mod_proxy.html">proxy module</a>. You must make
|
|
sure that the substitution string is a valid URI
|
|
(typically starting with
|
|
<code>http://</code><em>hostname</em>) which can be
|
|
handled by the Apache proxy module. If not, you will get an
|
|
error from the proxy module. Use this flag to achieve a
|
|
more powerful implementation of the <a
|
|
href="mod_proxy.html#proxypass">ProxyPass</a> directive,
|
|
to map remote content into the namespace of the local
|
|
server.
|
|
|
|
<p>Note: <module>mod_proxy</module> must be enabled in order
|
|
to use this flag.</p>
|
|
</dd>
|
|
|
|
<dt>
|
|
'<code>passthrough|PT</code>'
|
|
(pass through to next
|
|
handler)</dt><dd>
|
|
This flag forces the rewrite engine to set the
|
|
<code>uri</code> field of the internal
|
|
<code>request_rec</code> structure to the value of the
|
|
<code>filename</code> field. This flag is just a hack to
|
|
enable post-processing of the output of
|
|
<code>RewriteRule</code> directives, using
|
|
<code>Alias</code>, <code>ScriptAlias</code>,
|
|
<code>Redirect</code>, and other directives from
|
|
various URI-to-filename translators. For example, to rewrite
|
|
<code>/abc</code> to <code>/def</code> using
|
|
<module>mod_rewrite</module>, and then
|
|
<code>/def</code> to <code>/ghi</code> using
|
|
<module>mod_alias</module>:
|
|
<example>
|
|
RewriteRule ^/abc(.*) /def$1 [PT]<br />
|
|
Alias /def /ghi
|
|
</example>
|
|
If you omit the <code>PT</code> flag,
|
|
<module>mod_rewrite</module> will rewrite
|
|
<code>uri=/abc/...</code> to
|
|
<code>filename=/def/...</code> as a full API-compliant
|
|
URI-to-filename translator should do. Then
|
|
<code>mod_alias</code> will try to do a
|
|
URI-to-filename transition, which will fail.
|
|
|
|
<p>Note: <strong>You must use this flag if you want to
|
|
mix directives from different modules which allow
|
|
URL-to-filename translators</strong>. The typical example
|
|
is the use of <module>mod_alias</module> and
|
|
<module>mod_rewrite</module>.</p>
|
|
|
|
<p>The <code>PT</code> flag implies the <code>L</code> flag:
|
|
rewriting will be stopped in order to pass the request to
|
|
the next phase of processing.</p>
|
|
</dd>
|
|
|
|
<dt>'<code>qsappend|QSA</code>'
|
|
(query string
|
|
append)</dt><dd>
|
|
This flag forces the rewrite engine to append the query
|
|
string part of the substitution string to the existing query string,
|
|
instead of replacing it. Use this when you want to add more
|
|
data to the query string via a rewrite rule. This rule has no net effect
|
|
unless your substitution explicitly provides a new query string.</dd>
|
|
|
|
<dt>'<code>redirect|R</code>
|
|
[=<em>code</em>]' (force <a id="redirect"
|
|
name="redirect">redirect</a>)</dt><dd>
|
|
<p>Prefix <em>Substitution</em> with
|
|
<code>http://thishost[:thisport]/</code> (which makes the
|
|
new URL a URI) to force a external redirection. If no
|
|
<em>code</em> is given, a HTTP response of 302 (MOVED
|
|
TEMPORARILY) will be returned. If you want to use other
|
|
response codes, simply specify the appropriate number or use
|
|
one of the following symbolic names: <code>temp</code>
|
|
(default), <code>permanent</code>,
|
|
<code>seeother</code>. Use this for rules to canonicalize
|
|
the URL and return it to the client - to translate
|
|
``<code>/~</code>'' into ``<code>/u/</code>'', or to always
|
|
append a slash to <code>/u/</code><em>user</em>, etc.<br />
|
|
<strong>Note:</strong> When you use this flag, make sure
|
|
that the substitution field is a valid URL! Otherwise, you
|
|
will be redirecting to an invalid location. Remember that
|
|
this flag on its own will only prepend
|
|
<code>http://thishost[:thisport]/</code> to the URL, and
|
|
rewriting will continue. Usually, you will want to stop
|
|
rewriting at this point, and redirect immediately. To stop
|
|
rewriting, you should add the 'L' flag.</p>
|
|
<p>While this is typically used for redirects, any valid status
|
|
code can be given here. If the status code is outside the redirect
|
|
range (300-399), then the <em>Substitution</em> string is dropped
|
|
and rewriting is stopped as if the <code>L</code> flag was
|
|
used.</p>
|
|
</dd>
|
|
|
|
<dt>'<code>skip|S</code>=<em>num</em>'
|
|
(skip next rule(s))</dt><dd>
|
|
This flag forces the rewriting engine to skip the next
|
|
<em>num</em> rules in sequence, if the current rule
|
|
matches. Use this to make pseudo if-then-else constructs:
|
|
The last rule of the then-clause becomes
|
|
<code>skip=N</code>, where N is the number of rules in the
|
|
else-clause. (This is <strong>not</strong> the same as the
|
|
'chain|C' flag!)</dd>
|
|
|
|
<dt>
|
|
'<code>type|T</code>=<em>MIME-type</em>'
|
|
(force MIME type)</dt><dd>
|
|
Force the <glossary>MIME-type</glossary> of the target file to be
|
|
<em>MIME-type</em>. This can be used to
|
|
set up the content-type based on some conditions.
|
|
If used in per-directory context, use only <code>-</code> (dash)
|
|
as the substitution, otherwise the MIME-type set with this flag
|
|
is lost due to an internal re-processing.</dd>
|
|
</dl>
|
|
|
|
|
|
<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>
|
|
|
|
<note><pre>
|
|
<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 /otherpath/pathinfo
|
|
|
|
^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
|
|
via external redirection
|
|
|
|
^/somepath(.*) /otherpath$1 [P] doesn't make sense, not supported
|
|
---------------------------------------------- ----------------------------------
|
|
^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
|
|
|
|
^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
|
|
via external redirection
|
|
|
|
^/somepath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported
|
|
---------------------------------------------- ----------------------------------
|
|
^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
|
|
via external redirection
|
|
|
|
^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
|
|
via external redirection
|
|
(the [R] flag is redundant)
|
|
|
|
^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
|
|
via internal proxy
|
|
</pre></note>
|
|
|
|
<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>
|
|
|
|
<note><pre>
|
|
<strong>Given Rule</strong> <strong>Resulting Substitution</strong>
|
|
---------------------------------------------- ----------------------------------
|
|
^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo
|
|
|
|
^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo
|
|
via external redirection
|
|
|
|
^localpath(.*) otherpath$1 [P] doesn't make sense, not supported
|
|
---------------------------------------------- ----------------------------------
|
|
^localpath(.*) /otherpath$1 /otherpath/pathinfo
|
|
|
|
^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
|
|
via external redirection
|
|
|
|
^localpath(.*) /otherpath$1 [P] doesn't make sense, not supported
|
|
---------------------------------------------- ----------------------------------
|
|
^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
|
|
|
|
^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
|
|
via external redirection
|
|
|
|
^localpath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported
|
|
---------------------------------------------- ----------------------------------
|
|
^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
|
|
via external redirection
|
|
|
|
^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
|
|
via external redirection
|
|
(the [R] flag is redundant)
|
|
|
|
^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
|
|
via internal proxy
|
|
</pre></note>
|
|
</usage>
|
|
</directivesynopsis>
|
|
</modulesynopsis>
|