can be used in per-directory config files
(<code>.htaccess</code>). In such a case, it will act locally,
stripping the local directory prefix before processing, and applying
- rewrite rules only to the remainder. When processing is complete, the
+ rewrite rules only to the remainder. When processing is complete, the
prefix is automatically added back to the
path. The default setting is; <code class="directive">RewriteBase</code> <em>physical-directory-path</em></p>
or URL-base is. By default this prefix is the corresponding
filepath itself. <strong>However, for most websites, URLs are NOT
directly related to physical filename paths, so this
- assumption will often be wrong!</strong> Therefore, you can
+ assumption will often be wrong!</strong> Therefore, you can
use the <code>RewriteBase</code> directive to specify the
correct URL-prefix.</p>
has to be re-injected into the Apache kernel, as if it
were a new request. (See <a href="../rewrite/rewrite_tech.html">mod_rewrite technical
details</a>.)
- This is not the serious overhead it may seem to be -
- this re-injection is completely internal to the
- Apache server (and the same procedure is used by
- many other operations within Apache).</p>
+ This is not the serious overhead it may seem to be -
+ this re-injection is completely internal to the
+ Apache server (and the same procedure is used by
+ many other operations within Apache).</p>
</div>
</table>
<p>The <code class="directive">RewriteCond</code> directive defines a
rule condition. One or more <code class="directive">RewriteCond</code>
- can precede a <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
+ can precede a <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
directive. The following rule is then only used if both
the current state of the URI matches its pattern, <strong>and</strong> if these conditions are met.</p>
backreferences of the form <strong><code>$N</code></strong>
(0 <= N <= 9), which provide access to the grouped
parts (in parentheses) of the pattern, from the
- <code>RewriteRule</code> which is subject to the current
+ <code>RewriteRule</code> which is subject to the current
set of <code>RewriteCond</code> conditions.
</li>
<li>
</li>
<li>
<strong>Server-Variables</strong>: These are variables of
- the form
+ the form
<strong><code>%{</code> <em>NAME_OF_VARIABLE</em>
<code>}</code></strong>
where <em>NAME_OF_VARIABLE</em> can be a string taken
- from the following list:
+ from the following list:
<table>
<li>
<code>%{ENV:variable}</code>, where <em>variable</em> can be
- any environment variable, is also available.
+ any environment variable, is also available.
This is looked-up via internal
Apache structures and (if not found there) via
<code>getenv()</code> from the Apache server process.</li>
<code>%{LA-U:variable}</code> can be used for look-aheads which perform
an internal (URL-based) sub-request to determine the final
value of <em>variable</em>. This can be used to access
- variable for rewriting which is not available at the current
+ variable for rewriting which is not available at the current
stage, but will be set in a later phase.
<p>For instance, to rewrite according to the
<code>REMOTE_USER</code> variable from within the
<li>
There are some special variants of <em>CondPatterns</em>.
Instead of real regular expression strings you can also
- use one of the following:
+ use one of the following:
<ul>
- <li>'<strong><CondPattern</strong>' (lexicographically
+ <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
<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
+ 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
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 -
+ subrequest to do the check, so use it with care -
it can impact your server's performance!</li>
</ul>
<ul>
<li>'<strong><code>nocase|NC</code></strong>'
(<strong>n</strong>o <strong>c</strong>ase)<br />
- This makes the test case-insensitive - differences
+ 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
'<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:
+ instead of the implicit AND. Typical example:
<div class="example"><pre>
RewriteCond %{REMOTE_HOST} ^host1.* [OR]
RewriteRule ^/$ /homepage.std.html [L]
</pre></div>
- <p>Explanation: If you use a browser which identifies itself
+ <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
+ 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
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
-</table>
+</table>
<p>The <code class="directive">RewriteEngine</code> directive enables or
disables the runtime rewriting engine. If it is set to
<li>
<strong>Standard Plain Text</strong><br />
MapType: <code>txt</code>, MapSource: Unix filesystem
- path to valid regular file
+ path to valid regular file
<p>This is the standard rewriting map feature where the
<em>MapSource</em> is a plain ASCII file containing
<li>
<strong>Randomized Plain Text</strong><br />
MapType: <code>rnd</code>, MapSource: Unix filesystem
- path to valid regular file
+ path to valid regular file
<p>This is identical to the Standard Plain Text variant
above but with a special post-processing feature: After
<li>
<strong>Internal Function</strong><br />
MapType: <code>int</code>, MapSource: Internal Apache
- function
+ function
<p>Here, the source is an internal Apache function.
Currently you cannot create your own, but the following
<li>
<strong>External Rewriting Program</strong><br />
MapType: <code>prg</code>, MapSource: Unix filesystem
- path to valid regular file
+ 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
<p>External rewriting programs are not started if they're defined in a
context that does not have <code class="directive">RewriteEngine</code> set to
<code>on</code></p>.
-
+
<p>A trivial program which will implement a 1:1 map (<em>i.e.</em>,
key == value) could be:</p>
<ol>
<li>``<em>Keep it simple, stupid</em>'' (KISS).
- If this program hangs, it will cause Apache to hang
+ 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 <code class="directive"><a href="#rewritelock">RewriteLock</a></code> directive can
- be used to define a lockfile which mod_rewrite can use to synchronize
+ <li>The <code class="directive"><a href="#rewritelock">RewriteLock</a></code> 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>
<p>The <code class="directive">RewriteOptions</code> directive sets some
special options for the current per-server or per-directory
- configuration. The <em>Option</em> string can currently
+ configuration. The <em>Option</em> string can currently
only be one of the following:</p>
<dl>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
</table>
<p>The <code class="directive">RewriteRule</code> directive is the real
- rewriting workhorse. The directive can occur more than once,
+ 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>
Introduction</a>.</p>
<p>In mod_rewrite, the NOT character
- ('<code>!</code>') is also available as a possible pattern
+ ('<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
default rule.</p>
<div class="note"><h3>Note</h3>
-When using the NOT character to negate a pattern, you cannot include
-grouped wildcard parts in that pattern. This is because, when the
-pattern does NOT match (ie, the negation matches), there are no
+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!
</div>
<dd>Designates the location on the file-system of the resource
to be delivered to the client.</dd>
- <dt>URL-path</dt>
+ <dt>URL-path</dt>
<dd>A <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>-relative path to the
resource to be served. Note that <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
(<code>${mapname:key|default}</code>)</li>
</ol>
- <p>Back-references are identifiers of the form
+ <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
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
+ 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
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>
+ <code>[QSA]</code> flag.</p>
</div>
- <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">actions</a> to be performed by
+ <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
+ directive. <em>Flags</em> is a comma-separated list, surround by square
brackets, of any of the following flags: </p>
<dl>
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 -
+ 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
<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 <code class="directive">RewriteRule</code>
- compares against is the concatenation of the current values of the URI
- and PATH_INFO.</p>
+ 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
+ <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
<code class="directive">RewriteRule</code> directives, without regard for
- which parts of the URI came from the current PATH_INFO, the final
+ 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
+ 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
+ completes. Subsequent rules during this round of processing will see
+ only the direct result of substitutions, without any PATH_INFO
appended.</p></dd>
<dt>
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>).
+ 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
+ <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).
+ 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>
Force the Content-handler of the target file to be
<em>Content-handler</em>. For instance, this can be used to
simulate the <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> directive
- <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>,
+ <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>,
which internally forces all files
inside the mapped directory to have a handler of
``<code>cgi-script</code>''.<br />
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
+ the output, as in
<div class="example"><p><code>
RewriteRule ^/foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
</code></p></div>
which would turn '<code>/foo/zed</code>' into a safe
- request for '<code>/bar?arg=P1=zed</code>'.
+ request for '<code>/bar?arg=P1=zed</code>'.
</dd>
<dt>
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
+ 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>
'<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
+ 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
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.
+ server.
<p>Note: <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> must be enabled in order
to use this flag.</p>
<code>/abc</code> to <code>/def</code> using
<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>, and then
<code>/def</code> to <code>/ghi</code> using
- <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code>:
+ <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code>:
<div class="example"><p><code>
RewriteRule ^/abc(.*) /def$1 [PT]<br />
Alias /def /ghi
</code></p></div>
If you omit the <code>PT</code> flag,
- <code>mod_rewrite</code> will rewrite
+ <code>mod_rewrite</code> 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.
+ 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
<div class="note"><h3>Home directory expansion</h3>
<p> When the substitution string begins with a string
resembling "/~user" (via explicit text or backreferences), mod_rewrite performs
-home directory expansion independent of the presence or configuration
+home directory expansion independent of the presence or configuration
of <code class="module"><a href="../mod/mod_userdir.html">mod_userdir</a></code>.</p>
<p> This expansion does not occur when the <em>PT</em>
</div>
<div class="note"><h3>Per-directory Rewrites</h3>
-
+
<p>The rewrite engine may be used in <a href="../howto/htaccess.html">.htaccess</a> files. To enable the
rewrite engine for these files you need to set
"<code>RewriteEngine On</code>" <strong>and</strong>
(<code>/physical/path/to/somepath/.htacccess</code>, with
<code>RewriteBase /somepath</code>)<br />
for request ``<code>GET
- /somepath/localpath/pathinfo</code>'':</strong><br />
+ /somepath/localpath/pathinfo</code>'':</strong><br />
</p>
<div class="note"><pre>
projects / apache / commitdiff