mod_rewrite.html revision 71a5a10c13925dbe09aa5296f35edb6b5d29e9a0
842ae4bd224140319ae7feec1872b93dfd491143fielding<!--%hypertext -->
842ae4bd224140319ae7feec1872b93dfd491143fielding<!-- Documentation for the mod_rewrite Apache module -->
04891cf70e0bfc38bfb027541dc821f04c754ff7nd<!--#include virtual="header.html" -->
04891cf70e0bfc38bfb027541dc821f04c754ff7ndThis module is contained in the <code>mod_rewrite.c</code> file, with Apache
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding1.2 and later. It provides a rule-based rewriting engine to rewrite requested
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingURLs on the fly. <code>mod_rewrite</code> is not compiled into the server by
e8f95a682820a599fe41b22977010636be5c2717jimdefault. To use <code>mod_rewrite</code> you have to enable the following line
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingin the server build Configuration file:
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding Module rewrite_module mod_rewrite.o
fc9b2e8809c305f340d86a789566f8abb1ca8a19martinThis module uses a rule-based rewriting engine (based on a
fc9b2e8809c305f340d86a789566f8abb1ca8a19martinregular-expression parser) to rewrite requested URLs on the fly.
572f5b8a84bb399e51b02a562776f4aec119aa95pquernaIt supports an unlimited number of additional rule conditions (which can
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaoperate on a lot of variables, including HTTP headers) for granular
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingmatching and external database lookups (either via plain text
e8f95a682820a599fe41b22977010636be5c2717jimtables, DBM hash files or external processes) for advanced URL
b0bd17753ab27dbe1e9aa66565beaa33e02241e3pquernasubstitution.
b0bd17753ab27dbe1e9aa66565beaa33e02241e3pquernaIt operates on the full URLs (including the PATH_INFO part) both in
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingper-server context (httpd.conf) and per-dir context (.htaccess) and even
b0bd17753ab27dbe1e9aa66565beaa33e02241e3pquernacan generate QUERY_STRING parts on result. The rewritten result can lead to internal sub-processing, external request redirection or to internal proxy throughput.
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingThe latest version can be found on<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<a href="http://www.engelschall.com/sw/mod_rewrite/">
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<code><b>http://www.engelschall.com/sw/mod_rewrite/</b></code></a>
526cb5203706657872bda6080799947fbd7981e6fuankgCopyright © 1996,1997 <b>The Apache Group</b>, All rights reserved.<br>
0d022b0e686ad8cf25728b607e18c928e9d135e7takashiCopyright © 1996,1997 <i>Ralf S. Engelschall</i>, All rights reserved.
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<blockquote>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna <a href="mailto:rse@engelschall.com"><tt>rse@engelschall.com</tt></a><br>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <a href="http://www.engelschall.com/"><tt>www.engelschall.com</tt></a>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding</blockquote>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<!--%hypertext -->
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<!--/%hypertext -->
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<!--%hypertext -->
3d96ee83babeec32482c9082c9426340cee8c44dwrowe<!--/%hypertext -->
066877f1a045103acfdd376d48cdd473c33f409bdougm<strong>Syntax:</strong> <code>RewriteEngine</code> {<code>on,off</code>}<br>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<strong>Default:</strong> <strong><code>RewriteEngine off</code></strong><br>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<strong>Context:</strong> server config, virtual host, per-directory config<br>
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingThe <tt>RewriteEngine</tt> directive enables or disables the
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaruntime rewriting engine. If it is set to <code>off</code> this module does
63a2b23aa46d7c800061bcb79b7406fd6545679apquernano runtime processing at all. It does not even update the <tt>SCRIPT_URx</tt>
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingenvironment variables.
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaUse this directive to disable the module instead of commenting out
b0bd17753ab27dbe1e9aa66565beaa33e02241e3pquerna<strong>Syntax:</strong> <code>RewriteOptions</code> <em>Option</em> ...<br>
b38e1e2f118f67818f88faee827f4b3a2881e908sf<strong>Context:</strong> server config, virtual host, per-directory config<br>
b38e1e2f118f67818f88faee827f4b3a2881e908sfThe <tt>RewriteOption</tt> directive sets some special options for the
b38e1e2f118f67818f88faee827f4b3a2881e908sfcurrent per-server or per-directory configuration. The <em>Option</em>
b38e1e2f118f67818f88faee827f4b3a2881e908sfstrings can be one of the following:
b38e1e2f118f67818f88faee827f4b3a2881e908sf This forces the current configuration to inherit the configuration of the
b38e1e2f118f67818f88faee827f4b3a2881e908sf parent. In per-virtual-server context this means that the maps,
b38e1e2f118f67818f88faee827f4b3a2881e908sf conditions and rules of the main server gets inherited. In per-directory
b38e1e2f118f67818f88faee827f4b3a2881e908sf context this means that conditions and rules of the parent directory's
b38e1e2f118f67818f88faee827f4b3a2881e908sf<strong>Syntax:</strong> <code>RewriteLog</code> <em>Filename</em><br>
b0bd17753ab27dbe1e9aa66565beaa33e02241e3pquernaThe <tt>RewriteLog</tt> directive sets the name of the file to which the
b0bd17753ab27dbe1e9aa66565beaa33e02241e3pquernaserver logs any rewriting actions it performs. If the name does not begin
b38e1e2f118f67818f88faee827f4b3a2881e908sfwith a slash ('<tt>/</tt>') then it is assumed to be relative to the
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna<em>Server Root</em>. The directive should occur only once per server
b38e1e2f118f67818f88faee827f4b3a2881e908sf<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaTo disable the logging of rewriting actions it is not recommended
b38e1e2f118f67818f88faee827f4b3a2881e908sfto <code>/dev/null</code>, because although the rewriting engine does
b38e1e2f118f67818f88faee827f4b3a2881e908sfnot create output to a logfile it still creates the logfile
b38e1e2f118f67818f88faee827f4b3a2881e908sfoutput internally. <b>This will slow down the server with no advantage to the
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaadministrator!</b>
b38e1e2f118f67818f88faee827f4b3a2881e908sfTo disable logging either remove or comment out the
b38e1e2f118f67818f88faee827f4b3a2881e908sf<tt>RewriteLog</tt> directive or use <tt>RewriteLogLevel 0</tt>!
b0bd17753ab27dbe1e9aa66565beaa33e02241e3pquerna<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
b38e1e2f118f67818f88faee827f4b3a2881e908sfSECURITY: See the <a
b38e1e2f118f67818f88faee827f4b3a2881e908sfhref="http://www.apache.org/docs/misc/security_tips.html">Apache Security
b38e1e2f118f67818f88faee827f4b3a2881e908sfTips</a> document for details on why your security could be compromised if the
b38e1e2f118f67818f88faee827f4b3a2881e908sfdirectory where logfiles are stored is writable by anyone other than the user
b38e1e2f118f67818f88faee827f4b3a2881e908sfthat starts the server.
b38e1e2f118f67818f88faee827f4b3a2881e908sf<blockquote>
b38e1e2f118f67818f88faee827f4b3a2881e908sf</blockquote>
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna<a name="RewriteLogLevel"><h3>RewriteLogLevel</h3></a>
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<strong>Syntax:</strong> <code>RewriteLogLevel</code> <em>Level</em><br>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<strong>Default:</strong> <strong><code>RewriteLogLevel 0</code></strong><br>
572f5b8a84bb399e51b02a562776f4aec119aa95pquerna<strong>Context:</strong> server config, virtual host<br>
b38e1e2f118f67818f88faee827f4b3a2881e908sfThe <tt>RewriteLogLevel</tt> directive set the verbosity level of the rewriting
b38e1e2f118f67818f88faee827f4b3a2881e908sflogfile. The default level 0 means no logging, while 9 or more means
b38e1e2f118f67818f88faee827f4b3a2881e908sfthat practically all actions are logged.
572f5b8a84bb399e51b02a562776f4aec119aa95pquernaTo disable the logging of rewriting actions simply set <em>Level</em> to 0.
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquernaThis disables all rewrite action logs.
572f5b8a84bb399e51b02a562776f4aec119aa95pquerna<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
b38e1e2f118f67818f88faee827f4b3a2881e908sf<b>Notice:</b> Using a high value for <i>Level</i> will slow down your Apache
b38e1e2f118f67818f88faee827f4b3a2881e908sfserver dramatically! Use the rewriting logfile only for debugging or at least
572f5b8a84bb399e51b02a562776f4aec119aa95pquerna<blockquote>
572f5b8a84bb399e51b02a562776f4aec119aa95pquernaRewriteLogLevel 3
b38e1e2f118f67818f88faee827f4b3a2881e908sf</blockquote>
b38e1e2f118f67818f88faee827f4b3a2881e908sf<strong>Syntax:</strong> <code>RewriteMap</code> <em>Mapname</em> <code>{txt,dbm,prg}:</code><em>Filename</em><br>
572f5b8a84bb399e51b02a562776f4aec119aa95pquernaThe <tt>RewriteMap</tt> directive defines an external <em>Rewriting Map</em>
63a2b23aa46d7c800061bcb79b7406fd6545679apquernawhich can be used inside rule substitution strings by the mapping-functions
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaThe <a name="mapfunc"><em>Mapname</em></a> is the name of the map and will
63a2b23aa46d7c800061bcb79b7406fd6545679apquernabe used to specify a mapping-function for the substitution strings of a
572f5b8a84bb399e51b02a562776f4aec119aa95pquernarewriting rule via
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<code>${</code> <em>Mapname</em> <code>:</code> <em>LookupKey</em>
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquernaWhen such a directive occurs the map <em>Mapname</em>
63a2b23aa46d7c800061bcb79b7406fd6545679apquernais consulted and the key <em>LookupKey</em> is looked-up. If the key is
63a2b23aa46d7c800061bcb79b7406fd6545679apquernafound, the map-function directive is substituted by <em>SubstValue</em>. If
63a2b23aa46d7c800061bcb79b7406fd6545679apquernathe key is not found then it is substituted by <em>DefaultValue</em>.
572f5b8a84bb399e51b02a562776f4aec119aa95pquernaThe <em>Filename</em> must be a valid Unix filepath, containing one
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingof the following formats:
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna This is a ASCII file which contains either blank lines, comment lines
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna (starting with a '#' character) or
572f5b8a84bb399e51b02a562776f4aec119aa95pquerna pairs - one per line. You can create such files either manually,
572f5b8a84bb399e51b02a562776f4aec119aa95pquerna using your favorite editor, or by using the programs
572f5b8a84bb399e51b02a562776f4aec119aa95pquerna <tt>mapcollect</tt> and <tt>mapmerge</tt> from the <tt>support</tt>
572f5b8a84bb399e51b02a562776f4aec119aa95pquerna To declare such a map prefix, <em>Filename</em> with a <code>txt:</code>
572f5b8a84bb399e51b02a562776f4aec119aa95pquerna string as in the following example:
572f5b8a84bb399e51b02a562776f4aec119aa95pquerna<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0">
572f5b8a84bb399e51b02a562776f4aec119aa95pquerna# map.real-to-user -- maps realnames to usernames
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaRalf.S.Engelschall rse # Bastard Operator From Hell
0e161c3b556697af1dd88b719c05d3af239682d5dougm<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0">
0e161c3b556697af1dd88b719c05d3af239682d5dougmRewriteMap real-to-host txt:/path/to/file/map.real-to-user
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna This is a binary NDBM format file containing the
38537ab5306f85fd865f1fc8a42469c18a2c0969stoddard same contents as the <em>Plain Text Format</b> files. You can create
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna such a file with any NDBM tool or with the <tt>dbmmanage</tt> program
38537ab5306f85fd865f1fc8a42469c18a2c0969stoddard from the <tt>support</tt> directory of the Apache distribution.
0e161c3b556697af1dd88b719c05d3af239682d5dougm To declare such a map prefix <em>Filename</em> with a <code>dbm:</code>
0e161c3b556697af1dd88b719c05d3af239682d5dougm This is a Unix executable, not a lookup file. To create it you can use
0e161c3b556697af1dd88b719c05d3af239682d5dougm the language of your choice, but the result has to be a run-able Unix
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna binary (i.e. either object-code or a script with the
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna magic cookie trick '<tt>#!/path/to/interpreter</tt>' as the first line).
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna This program gets started once at startup of the Apache servers and then
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna communicates with the rewriting engine over its <tt>stdin</tt> and
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna <tt>stdout</tt> file-handles. For each map-function lookup it will
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna receive the key to lookup as a newline-terminated string on
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna <tt>stdin</tt>. It then has to give back the looked-up value as a
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna newline-terminated string on <tt>stdout</tt> or the four-character string
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna ``<tt>NULL</tt>'' if it fails (i.e. there is no corresponding value
0e161c3b556697af1dd88b719c05d3af239682d5dougm for the given key). A trivial program which will implement a 1:1 map
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna (i.e. key == value) could be:
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0">
7b6ba9c468f26bdb3492d5e8cb79628a3b04e8c8wrowewhile (<STDIN>) {
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna # ...here any transformations
22c347c08cd77d5e2c32536b467b389fd33d631fpquerna # or lookups should occur...
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna <li>``<i>Keep the program simple, stupid</i>'' (KISS), because
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna if this program hangs it will lead to a hang of the Apache server
0e161c3b556697af1dd88b719c05d3af239682d5dougm when the rule occurs.
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna <li>Avoid one common mistake: never do buffered I/O on <tt>stdout</tt>!
0e161c3b556697af1dd88b719c05d3af239682d5dougm This will cause a deadloop! Hence the ``<tt>$|=1</tt>'' in the above
0e161c3b556697af1dd88b719c05d3af239682d5dougm To declare such a map prefix <em>Filename</em> with a <code>prg:</code>
0e161c3b556697af1dd88b719c05d3af239682d5dougmThe <tt>RewriteMap</tt> directive can occur more than once. For each
0e161c3b556697af1dd88b719c05d3af239682d5dougmmapping-function use one <tt>RewriteMap</tt> directive to declare its
0e161c3b556697af1dd88b719c05d3af239682d5dougmrewriting mapfile. While you cannot <b>declare</b> a map in per-directory
0e161c3b556697af1dd88b719c05d3af239682d5dougmcontext it is of course possible to <b>use</b> this map in per-directory
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
0e161c3b556697af1dd88b719c05d3af239682d5dougmFor plain text and DBM format files the looked-up keys are cached in-core
0e161c3b556697af1dd88b719c05d3af239682d5dougmuntil the <tt>mtime</tt> of the mapfile changes or the server does a
0e161c3b556697af1dd88b719c05d3af239682d5dougmrestart. This way you can have map-functions in rules which are used
0e161c3b556697af1dd88b719c05d3af239682d5dougmfor <b>every</b> request. This is no problem, because the external lookup
0e161c3b556697af1dd88b719c05d3af239682d5dougmonly happens once!
0e161c3b556697af1dd88b719c05d3af239682d5dougm<strong>Syntax:</strong> <code>RewriteBase</code> <em>BaseURL</em><br>
0e161c3b556697af1dd88b719c05d3af239682d5dougm<strong>Default:</strong> <em>default is the physical directory path</em><br>
0e161c3b556697af1dd88b719c05d3af239682d5dougmThe <tt>RewriteBase</tt> directive explicitly sets the base URL for
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquernaper-directory rewrites. As you will see below, <tt>RewriteRule</tt> can be
0e161c3b556697af1dd88b719c05d3af239682d5dougmused in per-directory config files (<tt>.htaccess</tt>). There it will act
63a2b23aa46d7c800061bcb79b7406fd6545679apquernalocally, i.e. the local directory prefix is stripped at this stage of
0e161c3b556697af1dd88b719c05d3af239682d5dougmprocessing and your rewriting rules act only on the remainder. At the end
504bab8dd806efd02cba018975e9f48f35bebe49wroweit is automatically added.
0e161c3b556697af1dd88b719c05d3af239682d5dougmWhen a substitution occurs for a new URL, this module has to
0e161c3b556697af1dd88b719c05d3af239682d5dougmre-inject the URL into the server processing. To be able to do this it needs
0e161c3b556697af1dd88b719c05d3af239682d5dougmto know what the corresponding URL-prefix or URL-base is. By default this
0e161c3b556697af1dd88b719c05d3af239682d5dougmprefix is the corresponding filepath itself. <b>But at most websites URLs are
504bab8dd806efd02cba018975e9f48f35bebe49wrowe<b>NOT</b> directly related to physical filename paths, so this assumption
0e161c3b556697af1dd88b719c05d3af239682d5dougmwill be usually be wrong!</b> There you have to use the <tt>RewriteBase</tt>
504bab8dd806efd02cba018975e9f48f35bebe49wrowedirective to specify the correct URL-prefix.
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingSo, if your webserver's URLs are <b>not</b> directly
63a2b23aa46d7c800061bcb79b7406fd6545679apquernarelated to physical file paths, you have to use <tt>RewriteBase</tt> in every
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<tt>.htaccess</tt> files where you want to use <tt>RewriteRule</tt>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<blockquote>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding Assume the following per-directory config file:
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0">
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding# /abc/def/.htaccess -- per-dir config file for directory /abc/def
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna# Remember: /abc/def is the physical path of /xyz, i.e. the server
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaRewriteEngine On
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna# let the server know that we are reached via /xyz and not
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaRewriteBase /xyz
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna# now the rewriting rules
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaRewriteRule ^oldstuff\.html$ newstuff.html
14625d3bf388e992e3d8d58bd8c797c3586f1e3ffuankgIn the above example, a request to <tt>/xyz/oldstuff.html</tt> gets correctly
002ae5b0c02b5302a9bf5deff96e7fae25426887fuankgrewritten to the physical file <tt>/abc/def/newstuff.html</tt>.
f8773e46a17ee5b2ca827a8631dd2e399ab1cc1bfuankg<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
002ae5b0c02b5302a9bf5deff96e7fae25426887fuankgThe following list gives detailed information about the internal
002ae5b0c02b5302a9bf5deff96e7fae25426887fuankgprocessing steps:
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaInternal Processing:
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias)
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule)
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase)
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias)
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaThis seems very complicated but is the correct Apache internal processing,
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernabecause the per-directory rewriting comes too late in the process. So,
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernawhen it occurs the (rewritten) request has to be re-injected into the Apache
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernakernel! BUT: While this seems like a serious overhead, it really isn't, because
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernathis re-injection happens fully internal to the Apache server and the same
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaprocedure is used by many other operations inside Apache. So, you can be
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernasure the design and implementation is correct.
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna</blockquote>
635d41272b8a1a8837f9ef13b3b663b9351f33afpquerna<strong>Syntax:</strong> <code>RewriteCond</code> <em>TestString</em> <em>CondPattern</em><br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<strong>Context:</strong> server config, virtual host, per-directory config<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaThe <tt>RewriteCond</tt> directive defines a rule condition. Precede a
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<tt>RewriteRule</tt> directive with one ore more <t>RewriteCond</tt>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaThe following rewriting rule is only used if its pattern matches the current
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernastate of the URI <b>AND</b> if these additional conditions apply, too.
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<em>TestString</em> is a string which contains server-variables of the form
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaof the following list:
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaHTTP_USER_AGENT<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaHTTP_REFERER<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaHTTP_COOKIE<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaHTTP_FORWARDED<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaHTTP_HOST<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaHTTP_PROXY_CONNECTION<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaHTTP_ACCEPT<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaREMOTE_ADDR<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaREMOTE_HOST<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaREMOTE_USER<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaREMOTE_IDENT<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaREQUEST_METHOD<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaSCRIPT_FILENAME<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaPATH_INFO<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaQUERY_STRING<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaAUTH_TYPE<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaDOCUMENT_ROOT<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaSERVER_ADMIN<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaSERVER_NAME<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaSERVER_PORT<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaSERVER_PROTOCOL<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaSERVER_SOFTWARE<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaSERVER_VERSION<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaTIME_YEAR<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaTIME_MON<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaTIME_DAY<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaTIME_HOUR<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaTIME_MIN<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaTIME_SEC<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaTIME_WDAY<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaAPI_VERSION<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaTHE_REQUEST<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaREQUEST_URI<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaREQUEST_FILENAME<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaIS_SUBREQ<br>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaThese variables all correspond to the similar named HTTP MIME-headers, C
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernavariables of the Apache server or <tt>struct tm</tt> fields of the Unix
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaSpecial Notes:
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<li>The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernavalue, i.e. the value of the <tt>filename</tt> field of the internal
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<tt>request_rec</tt> structure of the Apache server. The first name is just the
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernacommonly known CGI variable name while the second is the consistent
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernacounterpart to REQUEST_URI (which contains the value of the <tt>uri</tt>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<li>There is the special format: <tt>%{ENV:variable}</tt> where
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<i>variable</i> can be any environment variable. This is looked-up via
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernainternal Apache structures and (if not found there) via <tt>getenv()</tt> from
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernathe Apache server process.
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<li>There is the special format: <tt>%{HTTP:header}</tt> where
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<i>header</i> can be any HTTP MIME-header name. This is looked-up
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernafrom the HTTP request. Example: <tt>%{HTTP:Proxy-Connection}</tt>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernais the value of the HTTP header ``<tt>Proxy-Connection:</tt>''.
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<li>There is the special format: <tt>%{LA-U:url}</tt>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernafor look-aheads like <tt>-U</tt>. This performans a internal sub-request to
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<li>There is the special format: <tt>%{LA-F:file}</tt>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernafor look-aheads like <tt>-F</tt>. This performans a internal sub-request to
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<em>CondPattern</em> is the condition pattern, i.e. a regular expression
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernawhich gets applied to the current instance of the <em>TestString</em>, i.e.
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<em>TestString</em> gets evaluated and then matched against
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<em>Extended Regular Expression</em> with some additions:
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<li>You can precede the pattern string with a '<tt>!</tt>' character
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna(exclamation mark) to specify a <b>non</b>-matching pattern.
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaThere are some special variants of <em>CondPatterns</em>. Instead of real
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaregular expression strings you can also use one of the following:
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernatests if it exists and is a directory.
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquernatests if it exists and is a regular file.
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<li>'<b>-s</b>' (is regular file with <b>s</b>ize)<br>
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquernatests if it exists and is a regular file with size greater then zero.
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquernatests if it exists and is a symbolic link.
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna<li>'<b>-F</b>' (is existing file via subrequest)<br>
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquernaChecks if <i>TestString</i> is a valid file and accessible via all the
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquernaserver's currently-configured access controls for that path. This uses an
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquernainternal subrequest to determine the check, so use it with care because it
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquernadecreases your servers performance!
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaChecks if <i>TestString</i> is a valid URL and accessible via all the server's
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernacurrently-configured access controls for that path. This uses an internal
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernasubrequest to determine the check, so use it with care because it decreases
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernayour servers performance!
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaNotice: All of these tests can also be prefixed by a not ('!') character
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernato negate their meaning.
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquernaAdditionally you can set special flags for <em>CondPattern</em> by appending
297d4b81c28f934b34a05017106a7df27adae391minfrinas the third argument to the <tt>RewriteCond</tt> directive. <em>Flags</em>
38afe973dfa1b11f14841b1870f3b9c5b5355fe3trawickis a comma-separated list of the following flags:
48d2edbfb84e5559b5da0f8d614ccab805cc67a8rbb<li>'<strong><code>nocase|NC</code></strong>' (<b>n</b>o <b>c</b>ase)<br>
297d4b81c28f934b34a05017106a7df27adae391minfrin This makes the condition test case-insensitive, i.e. there is
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna no difference between 'A-Z' and 'a-z' both in the expanded
a1790fb35c4b352dab721370985c623a9f8f5062rpluem<li>'<strong><code>ornext|OR</code></strong>' (<b>or</b> next condition)<br>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding Use this to combine rule conditions with a local OR instead of the
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna implicit AND. Typical example:
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquernaRewriteCond %{REMOTE_HOST} ^host1.* [OR]
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaRewriteCond %{REMOTE_HOST} ^host2.* [OR]
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaRewriteCond %{REMOTE_HOST} ^host3.*
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingRewriteRule ...some special stuff for any of these hosts...
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna Without this flag you had to write down the cond/rule three times.
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<blockquote>
095e61d2bb0722ee85bca91e75ccd2fe53421435rbowenTo rewrite the Homepage of a site according to the ``<tt>User-Agent:</tt>''
095e61d2bb0722ee85bca91e75ccd2fe53421435rbowenheader of the request, you can use the following:
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaRewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaRewriteRule ^/$ /homepage.max.html [L]
095e61d2bb0722ee85bca91e75ccd2fe53421435rbowenRewriteCond %{HTTP_USER_AGENT} ^Lynx.*
095e61d2bb0722ee85bca91e75ccd2fe53421435rbowenRewriteRule ^/$ /homepage.min.html [L]
f0484231f96a9d95f5044c1c8cb33b322d6f9bcbdougmRewriteRule ^/$ /homepage.std.html [L]
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingInterpretation: If you use Netscape Navigator as your browser (which identifies
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingitself as 'Mozilla'), then you get the max homepage, which includes
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingFrames, etc. If you use the Lynx browser (which is Terminal-based), then you
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingget the min homepage, which contains no images, no tables, etc. If you
504bab8dd806efd02cba018975e9f48f35bebe49wroweuse any other browser you get the standard homepage.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding</blockquote>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<strong>Syntax:</strong> <code>RewriteRule</code> <em>Pattern</em> <em>Substitution</em><br>
572f5b8a84bb399e51b02a562776f4aec119aa95pquerna<strong>Context:</strong> server config, virtual host, per-directory config<br>
572f5b8a84bb399e51b02a562776f4aec119aa95pquernaThe <tt>RewriteRule</tt> directive is the real rewriting workhorse. The
572f5b8a84bb399e51b02a562776f4aec119aa95pquernadirective can occur more than once. Each directive then defines one single
572f5b8a84bb399e51b02a562776f4aec119aa95pquernarewriting rule. The <b>definition order</b> of these rules is
297d4b81c28f934b34a05017106a7df27adae391minfrin<b>important</b>, because this order is used when applying the rules at
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<a name="patterns"><em>Pattern</em></a> can be (for Apache 1.1.x a System
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaV8 and for Apache 1.2.x a POSIX) <a name="regexp">regular expression</a>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernawhich gets applied to the current URL. Here ``current'' means the value of the
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaURL when this rule gets applied. This may not be the original requested
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquernaURL, because there could be any number of rules before which already matched
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaand made alterations to it.
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaSome hints about the syntax of regular expressions:
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5>
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<strong><code>[</code></strong>chars<strong><code>]</code></strong> One of chars
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<strong><code>[^</code></strong>chars<strong><code>]</code></strong> None of chars
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<strong><code>?</code></strong> 0 or 1 of the preceding char
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<strong><code>*</code></strong> 0 or N of the preceding char
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<strong><code>+</code></strong> 1 or N of the preceding char
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<strong><code>\</code></strong>char escape that specific char
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna (e.g. for specifying the chars "<code>.[]()</code>" etc.)
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<strong><code>(</code></strong>string<strong><code>)</code></strong> Grouping of chars (the <b>N</b>th group can be used on the RHS with <code>$</code><b>N</b>)
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaAdditionally the NOT character ('<tt>!</tt>') is a possible pattern
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingprefix. This gives you the ability to negate a pattern; to say, for instance: ``<i>if
63a2b23aa46d7c800061bcb79b7406fd6545679apquernathe current URL does <b>NOT</b> match to this pattern</i>''. This can be used
63a2b23aa46d7c800061bcb79b7406fd6545679apquernafor special cases where it is better to match the negative pattern or as a
63a2b23aa46d7c800061bcb79b7406fd6545679apquernalast default rule.
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<b>Notice!</b> When using the NOT character to negate a pattern you cannot
63a2b23aa46d7c800061bcb79b7406fd6545679apquernahave grouped wildcard parts in the pattern. This is impossible because when
63a2b23aa46d7c800061bcb79b7406fd6545679apquernathe pattern does NOT match, there are no contents for the groups. In
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaconsequence, if negated patterns are used, you cannot use <tt>$N</tt> in the
63a2b23aa46d7c800061bcb79b7406fd6545679apquernasubstitution string!
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<a name="rhs"><em>Substitution</em></a> of a rewriting rule is the string
63a2b23aa46d7c800061bcb79b7406fd6545679apquernawhich is substituted for (or replaces) the original URL for which
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<em>Pattern</em> matched. Beside plain text you can use
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<li>server-variables as in rule condition test-strings (<code>%{VARNAME}</code>)
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<li><a href="#mapfunc">mapping-function</a> calls (<code>${mapname:key|default}</code>)
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaBack-references are <code>$</code><b>N</b> (<b>N</b>=1..9) identifiers which
63a2b23aa46d7c800061bcb79b7406fd6545679apquernawill be replaced by the contents of the <b>N</b>th group of the matched
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<em>Pattern</em>. The server-variables are the same as for the
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<em>TestString</em> of a <tt>RewriteCond</tt> directive. The
63a2b23aa46d7c800061bcb79b7406fd6545679apquernamapping-functions come from the <tt>RewriteMap</tt> directive and are
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaexplained there. These three types of variables are expanded in the order of
63a2b23aa46d7c800061bcb79b7406fd6545679apquernathe above list.
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaAs already mentioned above, all the rewriting rules are applied to the
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<em>Substitution</em> (in the order of definition in the config file). The
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaURL is <b>completely replaced</b> by the <em>Substitution</em> and the
63a2b23aa46d7c800061bcb79b7406fd6545679apquernarewriting process goes on until there are no more rules (unless explicitly
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaterminated by a <code><b>L</b></code> flag - see below).
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaThere is a special substitution string named '<tt>-</tt>' which means:
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<b>NO substitution</b>! Sounds silly? No, it is useful to provide rewriting
63a2b23aa46d7c800061bcb79b7406fd6545679apquernarules which <b>only</b> match some URLs but do no substitution, e.g. in
297d4b81c28f934b34a05017106a7df27adae391minfrinconjunction with the <b>C</b> (chain) flag to be able to have more than one
63a2b23aa46d7c800061bcb79b7406fd6545679apquernapattern to be applied before a substitution occurs.
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<b>Notice</b>: There is a special feature. When you prefix a substitution
63a2b23aa46d7c800061bcb79b7406fd6545679apquernafield with <tt>http://</tt><em>thishost</em>[<em>:thisport</em>] then
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<b>mod_rewrite</b> automatically strips it out. This auto-reduction on
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaimplicit external redirect URLs is a useful and important feature when
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaused in combination with a mapping-function which generates the hostname
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingpart. Have a look at the first example in the example section below to
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingunderstand this.
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna<b>Remember:</b> An unconditional external redirect to your own server will
63a2b23aa46d7c800061bcb79b7406fd6545679apquernanot work with the prefix <tt>http://thishost</tt> because of this feature.
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaTo achieve such a self-redirect, you have to use the <b>R</b>-flag (see
504bab8dd806efd02cba018975e9f48f35bebe49wroweAdditionally you can set special flags for <em>Substitution</em> by appending
63a2b23aa46d7c800061bcb79b7406fd6545679apquernaas the third argument to the <tt>RewriteRule</tt> directive. <em>Flags</em> is a
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingcomma-separated list of the following flags:
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<li>'<strong><code>redirect|R</code>[=<i>code</i>]</strong>' (force <a name="redirect"><b>r</b>edirect</a>)<br>
03e76ec3a3fd1602bd3cdc80479c769c5bc505a6pquerna with <code>http://thishost[:thisport]/</code> (which makes the new URL a URI) to
69b3b88588e73701b14b6e925dedb339869fb12arbb force a external redirection. If no <i>code</i> is given a HTTP response
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding of 302 (MOVED TEMPORARILY) is used. If you want to use other response
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding codes in the range 300-400 just specify them as a number or use
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna one of the following symbolic names: <tt>temp</tt> (default), <tt>permanent</tt>,
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna Use it for rules which should
066877f1a045103acfdd376d48cdd473c33f409bdougm canonicalize the URL and gives it back to the client, e.g. translate
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding ``<code>/~</code>'' into ``<code>/u/</code>'' or always append a slash to
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <b>Notice:</b> When you use this flag, make sure that the
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding substitution field is a valid URL! If not, you are redirecting to an
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding invalid location! And remember that this flag itself only prefixes the
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna URL with <code>http://thishost[:thisport]/</code>, but rewriting goes on.
69b3b88588e73701b14b6e925dedb339869fb12arbb Usually you also want to stop and do the redirection immediately. To stop
69b3b88588e73701b14b6e925dedb339869fb12arbb the rewriting you also have to provide the 'L' flag.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<li>'<strong><code>forbidden|F</code></strong>' (force URL to be <b>f</b>orbidden)<br>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding This forces the current URL to be forbidden, i.e. it immediately sends
b38e1e2f118f67818f88faee827f4b3a2881e908sf back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with
b38e1e2f118f67818f88faee827f4b3a2881e908sf appropriate RewriteConds to conditionally block some URLs.
b38e1e2f118f67818f88faee827f4b3a2881e908sf<li>'<strong><code>gone|G</code></strong>' (force URL to be <b>g</b>one)<br>
b38e1e2f118f67818f88faee827f4b3a2881e908sf This forces the current URL to be gone, i.e. it immediately sends back a
b38e1e2f118f67818f88faee827f4b3a2881e908sf HTTP response of 410 (GONE). Use this flag to mark no longer existing
b38e1e2f118f67818f88faee827f4b3a2881e908sf pages as gone.
b38e1e2f118f67818f88faee827f4b3a2881e908sf<li>'<strong><code>proxy|P</code></strong>' (force <b>p</b>roxy)<br>
b38e1e2f118f67818f88faee827f4b3a2881e908sf This flag forces the substitution part to be internally forced as a proxy
63a2b23aa46d7c800061bcb79b7406fd6545679apquerna request and immediately (i.e. rewriting rule processing stops here) put
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding through the proxy module. You have to make sure that the substitution
b980ad7fdc218b4855cde9f75a747527f50c554dwrowe string is a valid URI (e.g. typically <tt>http://</tt>) which can
b38e1e2f118f67818f88faee827f4b3a2881e908sf be handled by the Apache proxy module. If not you get an error from
87f68933ff7dacde336496b689e93681b6ae3945trawick the proxy module. Use this flag to achieve a more powerful implementation
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding of the <tt>mod_proxy</tt> directive <tt>ProxyPass</tt>, to map
36ef8f77bffe75d1aa327882be1b5bdbe2ff567asf some remote stuff into the namespace of the local server.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding Notice: <b>You really have to put <tt>ProxyRequests On</tt> into your
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding server configuration to prevent proxy requests from leading to core-dumps
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding inside the Apache kernel. If you have not compiled in the proxy module,
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding then there is no core-dump problem, because mod_rewrite checks for
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm existence of the proxy module and if lost forbids proxy URLs. </b>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<li>'<strong><code>last|L</code></strong>' (<b>l</b>ast rule)<br>
language. Use this flag to restart the rewriting process, i.e. to
effect: if a rule matches, then processing continues as usual, i.e. the
<li>'<strong><code>nosubreq|NS</code></strong>' (used only if <b>n</b>o internal <b>s</b>ub-request)<br>
<li>'<strong><code>env|E=</code></strong><i>VAR</i>:<i>VAL</i>' (set <b>e</b>nvironment variable)<br>
^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
^/somepath(.*) http://thishost/otherpath$1 [P] not supported, because silly!
^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo
^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
^localpath(.*) http://thishost/otherpath$1 [P] not supported, because silly!
<!--#include virtual="footer.html" -->