src - OpenBSD base system

diff options


context:
space:
mode:

author	Henning Brauer <henning@cvs.openbsd.org>	2003-11-17 19:05:48 +0000
committer	Henning Brauer <henning@cvs.openbsd.org>	2003-11-17 19:05:48 +0000
commit	bff3be8216a04344fa6da2fce99c55476d469c57 (patch)
tree	a6afd213c5ebba12ba0ae32cfd7a46d8c549b4b4 /usr.sbin
parent	1763ed19f12089e1c3e06c867fb45fbf8531af41 (diff)

this is historic as of 1.3.29

Diffstat (limited to 'usr.sbin')

-rw-r--r--

usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html

2117

1 files changed, 0 insertions, 2117 deletions

diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html b/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html
deleted file mode 100644
index 341426057cc..00000000000
--- a/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html
+++ /dev/null

@@ -1,2117 +0,0 @@

-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

-

-

-

-<html xmlns="http://www.w3.org/1999/xhtml">

- <head>

- <meta name="generator" content="HTML Tidy, see www.w3.org" />

- <title>Apache module mod_rewrite</title>

- </head>

-

- <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"

- vlink="#000080" alink="#FF0000">

- <blockquote>

-

- <div align="CENTER">

- <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" />

- <h3>Apache HTTP Server Version 1.3</h3>

- </div>

-

- <h1 align="CENTER">Module mod_rewrite

- URL Rewriting Engine</h1>

- This module provides a rule-based rewriting engine to

- rewrite requested URLs on the fly.

- <a href="module-dict.html#Status"

- rel="Help">Status:</a> Extension

- <a href="module-dict.html#SourceFile"

- rel="Help">Source File:</a>

- mod_rewrite.c

- <a href="module-dict.html#ModuleIdentifier"

- rel="Help">Module Identifier:</a>

- rewrite_module

- <a href="module-dict.html#Compatibility"

- rel="Help">Compatibility:</a> Available in

- Apache 1.2 and later.

- <hr noshade="noshade" size="1" />

-

- <h2>Summary</h2>

- <blockquote>

- ``The great thing about mod_rewrite is it gives you

- all the configurability and flexibility of Sendmail.

- The downside to mod_rewrite is that it gives you all

- the configurability and flexibility of Sendmail.''

- <div align="RIGHT">

- -- Brian Behlendorf

- Apache Group

- </div>

- </blockquote>

- <blockquote>

- `` Despite the tons of examples and docs,

- mod_rewrite is voodoo. Damned cool voodoo, but still

- voodoo. ''

- <div align="RIGHT">

- -- Brian Moore

- bem@news.cmc.net

- </div>

- </blockquote>

- Welcome to mod_rewrite, the Swiss Army Knife of URL

- manipulation!

- This module uses a rule-based rewriting engine (based on a

- regular-expression parser) to rewrite requested URLs on the

- fly. It supports an unlimited number of rules and an

- unlimited number of attached rule conditions for each rule to

- provide a really flexible and powerful URL manipulation

- mechanism. The URL manipulations can depend on various tests,

- for instance server variables, environment variables, HTTP

- headers, time stamps and even external database lookups in

- various formats can be used to achieve a really granular URL

- matching.

- This module operates on the full URLs (including the

- path-info part) both in per-server context

- (<code>httpd.conf</code>) and per-directory context

- (<code>.htaccess</code>) and can even generate query-string

- parts on result. The rewritten result can lead to internal

- sub-processing, external request redirection or even to an

- internal proxy throughput.

- But all this functionality and flexibility has its

- drawback: complexity. So don't expect to understand this

- entire module in just one day.

- This module was invented and originally written in April

- 1996

- and gifted exclusively to the The Apache Group in July 1997

- by

- <blockquote>

- <a href="http://www.engelschall.com/"><code>Ralf S.

- Engelschall</code></a>

- <a

- href="mailto:rse@engelschall.com"><code>rse@engelschall.com</code></a>

- <a

- href="http://www.engelschall.com/"><code>www.engelschall.com</code></a>

- </blockquote>

- <hr noshade="noshade" size="1" />

- <h2>Table Of Contents</h2>

- Internal Processing

- <ul>

- <li><a href="#InternalAPI">API Phases</a></li>

- <li><a href="#InternalRuleset">Ruleset Processing</a></li>

- <li><a href="#InternalBackRefs">Regex Back-Reference

- Availability</a></li>

- </ul>

- Configuration Directives

- <ul>

- <li><a href="#RewriteEngine">RewriteEngine</a></li>

- <li><a href="#RewriteOptions">RewriteOptions</a></li>

- <li><a href="#RewriteLog">RewriteLog</a></li>

- <li><a href="#RewriteLogLevel">RewriteLogLevel</a></li>

- <li><a href="#RewriteLock">RewriteLock</a></li>

- <li><a href="#RewriteMap">RewriteMap</a></li>

- <li><a href="#RewriteBase">RewriteBase</a></li>

- <li><a href="#RewriteCond">RewriteCond</a></li>

- <li><a href="#RewriteRule">RewriteRule</a></li>

- </ul>

- Miscellaneous

- <ul>

- <li><a href="#EnvVar">Environment Variables</a></li>

- <li><a href="#Solutions">Practical Solutions</a></li>

- </ul>

- <hr noshade="noshade" size="1" />

- <center>

- <h1><a id="Internal" name="Internal">Internal

- Processing</a></h1>

- </center>

- <hr noshade="noshade" size="1" />

- The internal processing of this module is very complex but

- needs to be explained once even to the average user to avoid

- common mistakes and to let you exploit its full

- functionality.

- <h2><a id="InternalAPI" name="InternalAPI">API

- Phases</a></h2>

- First you have to understand that when Apache processes a

- HTTP request it does this in phases. A hook for each of these

- phases is provided by the Apache API. Mod_rewrite uses two of

- these hooks: the URL-to-filename translation hook which is

- used after the HTTP request has been read but before any

- authorization starts and the Fixup hook which is triggered

- after the authorization phases and after the per-directory

- config files (<code>.htaccess</code>) have been read, but

- before the content handler is activated.

- So, after a request comes in and Apache has determined the

- corresponding server (or virtual server) the rewriting engine

- starts processing of all mod_rewrite directives from the

- per-server configuration in the URL-to-filename phase. A few

- steps later when the final data directories are found, the

- per-directory configuration directives of mod_rewrite are

- triggered in the Fixup phase. In both situations mod_rewrite

- rewrites URLs either to new URLs or to filenames, although

- there is no obvious distinction between them. This is a usage

- of the API which was not intended to be this way when the API

- was designed, but as of Apache 1.x this is the only way

- mod_rewrite can operate. To make this point more clear

- remember the following two points:

- <ol>

- <li>Although mod_rewrite rewrites URLs to URLs, URLs to

- filenames and even filenames to filenames, the API

- currently provides only a URL-to-filename hook. In Apache

- 2.0 the two missing hooks will be added to make the

- processing more clear. But this point has no drawbacks for

- the user, it is just a fact which should be remembered:

- Apache does more in the URL-to-filename hook than the API

- intends for it.</li>

- <li>

- Unbelievably mod_rewrite provides URL manipulations in

- per-directory context, i.e., within

- <code>.htaccess</code> files, although these are reached

- a very long time after the URLs have been translated to

- filenames. It has to be this way because

- <code>.htaccess</code> files live in the filesystem, so

- processing has already reached this stage. In other

- words: According to the API phases at this time it is too

- late for any URL manipulations. To overcome this chicken

- and egg problem mod_rewrite uses a trick: When you

- manipulate a URL/filename in per-directory context

- mod_rewrite first rewrites the filename back to its

- corresponding URL (which is usually impossible, but see

- the <code>RewriteBase</code> directive below for the

- trick to achieve this) and then initiates a new internal

- sub-request with the new URL. This restarts processing of

- the API phases.

- Again mod_rewrite tries hard to make this complicated

- step totally transparent to the user, but you should

- remember here: While URL manipulations in per-server

- context are really fast and efficient, per-directory

- rewrites are slow and inefficient due to this chicken and

- egg problem. But on the other hand this is the only way

- mod_rewrite can provide (locally restricted) URL

- manipulations to the average user.

- </li>

- </ol>

- Don't forget these two points!

- <h2><a id="InternalRuleset" name="InternalRuleset">Ruleset

- Processing</a></h2>

- Now when mod_rewrite is triggered in these two API phases, it

- reads the configured rulesets from its configuration

- structure (which itself was either created on startup for

- per-server context or during the directory walk of the Apache

- kernel for per-directory context). Then the URL rewriting

- engine is started with the contained ruleset (one or more

- rules together with their conditions). The operation of the

- URL rewriting engine itself is exactly the same for both

- configuration contexts. Only the final result processing is

- different.

- The order of rules in the ruleset is important because the

- rewriting engine processes them in a special (and not very

- obvious) order. The rule is this: The rewriting engine loops

- through the ruleset rule by rule (<code>RewriteRule</code>

- directives) and when a particular rule matches it optionally

- loops through existing corresponding conditions

- (<code>RewriteCond</code> directives). For historical reasons

- the conditions are given first, and so the control flow is a

- little bit long-winded. See Figure 1 for more details.

- <div align="CENTER">

- <table cellspacing="0" cellpadding="2" border="0">

- <tr>

- <td bgcolor="#CCCCCC"><img

- src="../images/mod_rewrite_fig1.gif" width="428"

- height="385"

- alt="[Needs graphics capability to display]" /></td>

- </tr>

- <tr>

- <td align="CENTER">Figure 1: The

- control flow through the rewriting ruleset</td>

- </tr>

- </table>

- </div>

- As you can see, first the URL is matched against the

- Pattern of each rule. When it fails mod_rewrite

- immediately stops processing this rule and continues with the

- next rule. If the Pattern matches, mod_rewrite looks

- for corresponding rule conditions. If none are present, it

- just substitutes the URL with a new value which is

- constructed from the string Substitution and goes on

- with its rule-looping. But if conditions exist, it starts an

- inner loop for processing them in the order that they are

- listed. For conditions the logic is different: we don't match

- a pattern against the current URL. Instead we first create a

- string TestString by expanding variables,

- back-references, map lookups, etc. and then we try

- to match CondPattern against it. If the pattern

- doesn't match, the complete set of conditions and the

- corresponding rule fails. If the pattern matches, then the

- next condition is processed until no more conditions are

- available. If all conditions match, processing is continued

- with the substitution of the URL with

- Substitution.

- <h2><a id="quoting" name="quoting">Quoting Special

- Characters</a></h2>

- As of Apache 1.3.20, special characters in

- TestString and Substitution strings can be

- escaped (that is, treated as normal characters without their

- usual special meaning) by prefixing them with a slosh ('\')

- character. In other words, you can include an actual

- dollar-sign character in a Substitution string by

- using '<code>\$</code>'; this keeps mod_rewrite from trying

- to treat it as a backreference.

- <h2><a id="InternalBackRefs" name="InternalBackRefs">Regex

- Back-Reference Availability</a></h2>

- One important thing here has to be remembered: Whenever you

- use parentheses in Pattern or in one of the

- CondPattern, back-references are internally created

- which can be used with the strings <code>$N</code> and

- <code>%N</code> (see below). These are available for creating

- the strings Substitution and TestString.

- Figure 2 shows to which locations the back-references are

- transfered for expansion.

- <div align="CENTER">

- <table cellspacing="0" cellpadding="2" border="0">

- <tr>

- <td bgcolor="#CCCCCC"><img

- src="../images/mod_rewrite_fig2.gif" width="381"

- height="179"

- alt="[Needs graphics capability to display]" /></td>

- </tr>

- <tr>

- <td align="CENTER">Figure 2: The

- back-reference flow through a rule</td>

- </tr>

- </table>

- </div>

- We know this was a crash course on mod_rewrite's internal

- processing. But you will benefit from this knowledge when

- reading the following documentation of the available

- directives.

- <hr noshade="noshade" size="1" />

- <center>

- <h1><a id="Configuration"

- name="Configuration">Configuration Directives</a></h1>

- </center>

- <hr noshade="noshade" size="1" />

- <h3><a id="RewriteEngine"

- name="RewriteEngine">RewriteEngine</a></h3>

- <a href="directive-dict.html#Syntax"

- rel="Help">Syntax:</a> RewriteEngine

- on|off

- <a href="directive-dict.html#Default"

- rel="Help">Default:</a> <code>RewriteEngine

- off</code>

- <a href="directive-dict.html#Context"

- rel="Help">Context:</a> server config,

- virtual host, directory, .htaccess

- <a href="directive-dict.html#Override"

- rel="Help">Override:</a> FileInfo

- <a href="directive-dict.html#Status"

- rel="Help">Status:</a> Extension

- <a href="directive-dict.html#Module"

- rel="Help">Module:</a> mod_rewrite.c

- <a href="directive-dict.html#Compatibility"

- rel="Help">Compatibility:</a> Apache

- 1.2

- The <code>RewriteEngine</code> directive enables or

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

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

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

- environment variables.

- Use this directive to disable the module instead of

- commenting out all the <code>RewriteRule</code>

- directives!

- Note that, by default, rewrite configurations are not

- inherited. This means that you need to have a

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

- in which you wish to use it.

- <hr noshade="noshade" size="1" />

- <h3><a id="RewriteOptions"

- name="RewriteOptions">RewriteOptions</a></h3>

- <a href="directive-dict.html#Syntax"

- rel="Help">Syntax:</a> RewriteOptions

- Option

- <a href="directive-dict.html#Default"

- rel="Help">Default:</a> <code>RewriteOptions

- MaxRedirects=10</code>

- <a href="directive-dict.html#Context"

- rel="Help">Context:</a> server config,

- virtual host, directory, .htaccess

- <a href="directive-dict.html#Override"

- rel="Help">Override:</a> FileInfo

- <a href="directive-dict.html#Status"

- rel="Help">Status:</a> Extension

- <a href="directive-dict.html#Module"

- rel="Help">Module:</a> mod_rewrite.c

- <a href="directive-dict.html#Compatibility"

- rel="Help">Compatibility:</a> Apache

- 1.2; <code>MaxRedirects</code> is available in Apache 1.3.28 and

- later

- The <code>RewriteOptions</code> directive sets some

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

- configuration. The Option strings can be one of the

- following:

- <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 are inherited.</dd>

- <dt><code>MaxRedirects=<var>number</var></code></dt>

- <dd>In order to prevent endless loops of internal redirects

- issued by per-directory <code>RewriteRule</code>s,

- <code>mod_rewrite</code> aborts the request after reaching a

- maximum number of such redirects and responds with an 500 Internal

- Server Error. If you really need more internal redirects than 10

- per request, you may increase the default to the desired value.</dd>

- </dl>

- <hr noshade="noshade" size="1" />

- <h3><a id="RewriteLog" name="RewriteLog">RewriteLog</a></h3>

- <a href="directive-dict.html#Syntax"

- rel="Help">Syntax:</a> RewriteLog

- file-path

- <a href="directive-dict.html#Default"

- rel="Help">Default:</a> None

- <a href="directive-dict.html#Context"

- rel="Help">Context:</a> server config,

- virtual host

- <a href="directive-dict.html#Override"

- rel="Help">Override:</a> Not

- applicable

- <a href="directive-dict.html#Status"

- rel="Help">Status:</a> Extension

- <a href="directive-dict.html#Module"

- rel="Help">Module:</a> mod_rewrite.c

- <a href="directive-dict.html#Compatibility"

- rel="Help">Compatibility:</a> Apache

- 1.2

- The <code>RewriteLog</code> directive sets the name of the

- file to which the server logs any rewriting actions it

- performs. If the name does not begin with a slash

- ('<code>/</code>') then it is assumed to be relative to the

- Server Root. The directive should occur only once

- per server config.

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>Note: To disable the logging of

- rewriting actions it is not recommended to set

- file-path to <code>/dev/null</code>, because

- although the rewriting engine does not then output to a

- logfile it still creates the logfile output internally.

- This will slow down the server with no advantage

- to the administrator! To disable logging either

- remove or comment out the <code>RewriteLog</code>

- directive or use <code>RewriteLogLevel 0</code>!</td>

- </tr>

- </table>

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>Security: See the <a

- href="../misc/security_tips.html">Apache Security

- Tips</a> document for details on why your security could

- be compromised if the directory where logfiles are stored

- is writable by anyone other than the user that starts the

- server.</td>

- </tr>

- </table>

- Example:

- <blockquote>

-<pre>

-RewriteLog "/usr/local/var/apache/logs/rewrite.log"

-</pre>

- </blockquote>

- <hr noshade="noshade" size="1" />

- <h3><a id="RewriteLogLevel"

- name="RewriteLogLevel">RewriteLogLevel</a></h3>

- <a href="directive-dict.html#Syntax"

- rel="Help">Syntax:</a> RewriteLogLevel

- Level

- <a href="directive-dict.html#Default"

- rel="Help">Default:</a>

- <code>RewriteLogLevel 0</code>

- <a href="directive-dict.html#Context"

- rel="Help">Context:</a> server config,

- virtual host

- <a href="directive-dict.html#Override"

- rel="Help">Override:</a> Not

- applicable

- <a href="directive-dict.html#Status"

- rel="Help">Status:</a> Extension

- <a href="directive-dict.html#Module"

- rel="Help">Module:</a> mod_rewrite.c

- <a href="directive-dict.html#Compatibility"

- rel="Help">Compatibility:</a> Apache

- 1.2

- The <code>RewriteLogLevel</code> directive sets the

- verbosity level of the rewriting logfile. The default level 0

- means no logging, while 9 or more means that practically all

- actions are logged.

- To disable the logging of rewriting actions simply set

- Level to 0. This disables all rewrite action

- logs.

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>Notice: Using a high value for

- Level will slow down your Apache server

- dramatically! Use the rewriting logfile at a

- Level greater than 2 only for debugging!</td>

- </tr>

- </table>

- Example:

- <blockquote>

-<pre>

-RewriteLogLevel 3

-</pre>

- </blockquote>

- <hr noshade="noshade" size="1" />

- <h3><a id="RewriteLock"

- name="RewriteLock">RewriteLock</a></h3>

- <a href="directive-dict.html#Syntax"

- rel="Help">Syntax:</a> RewriteLock

- file-path

- <a href="directive-dict.html#Default"

- rel="Help">Default:</a> None

- <a href="directive-dict.html#Context"

- rel="Help">Context:</a> server config

- <a href="directive-dict.html#Override"

- rel="Help">Override:</a> Not

- applicable

- <a href="directive-dict.html#Status"

- rel="Help">Status:</a> Extension

- <a href="directive-dict.html#Module"

- rel="Help">Module:</a> mod_rewrite.c

- <a href="directive-dict.html#Compatibility"

- rel="Help">Compatibility:</a> Apache

- 1.3

- This directive sets the filename for a synchronization

- lockfile which mod_rewrite needs to communicate with

- <samp>RewriteMap</samp> programs. 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.

- <hr noshade="noshade" size="1" />

- <h3><a id="RewriteMap" name="RewriteMap">RewriteMap</a></h3>

- <a href="directive-dict.html#Syntax"

- rel="Help">Syntax:</a> RewriteMap

- MapName MapType:MapSource

- <a href="directive-dict.html#Default"

- rel="Help">Default:</a> not used per

- default

- <a href="directive-dict.html#Context"

- rel="Help">Context:</a> server config,

- virtual host

- <a href="directive-dict.html#Override"

- rel="Help">Override:</a> Not

- applicable

- <a href="directive-dict.html#Status"

- rel="Help">Status:</a> Extension

- <a href="directive-dict.html#Module"

- rel="Help">Module:</a> mod_rewrite.c

- <a href="directive-dict.html#Compatibility"

- rel="Help">Compatibility:</a> Apache 1.2

- (partially), Apache 1.3

- The <code>RewriteMap</code> directive defines a

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

- The <a id="mapfunc" name="mapfunc">MapName</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:

- <blockquote>

- <code>${</code> MapName <code>:</code>

- LookupKey <code>}</code>

- <code>${</code> MapName <code>:</code>

- LookupKey <code>|</code> DefaultValue

- <code>}</code>

- </blockquote>

- When such a construct occurs the map MapName is

- consulted and the key LookupKey is looked-up. If the

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

- SubstValue. If the key is not found then it is

- substituted by DefaultValue or by the empty string

- if no DefaultValue was specified.

- The following combinations for MapType and

- MapSource can be used:

- <ul>

- <li>

- Standard Plain Text

- MapType: <code>txt</code>, MapSource: Unix filesystem

- path to valid regular file

- This is the standard rewriting map feature where the

- MapSource is a plain ASCII file containing

- either blank lines, comment lines (starting with a '#'

- character) or pairs like the following - one per

- line.

- <blockquote>

- MatchingKey

- SubstValue

- </blockquote>

- Example:

- <table border="0" cellspacing="1" cellpadding="5"

- bgcolor="#F0F0F0">

- <tr>

- <td>

-<pre>

-##

-## map.txt -- rewriting map

-##

-Ralf.S.Engelschall rse # Bastard Operator From Hell

-Mr.Joe.Average joe # Mr. Average

-</pre>

- </td>

- </tr>

- </table>

- <table border="0" cellspacing="1" cellpadding="5"

- bgcolor="#F0F0F0">

- <tr>

- <td>

-<pre>

-RewriteMap real-to-user txt:/path/to/file/map.txt

-</pre>

- </td>

- </tr>

- </table>

- </li>

- <li>

- Randomized Plain Text

- MapType: <code>rnd</code>, MapSource: Unix filesystem

- path to valid regular file

- 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. Although this sounds crazy and useless,

- it was actually designed for load balancing in a reverse

- proxy situation where the looked up values are server

- names. Example:

- <table border="0" cellspacing="1" cellpadding="5"

- bgcolor="#F0F0F0">

- <tr>

- <td>

-<pre>

-##

-## map.txt -- rewriting map

-##

-static www1|www2|www3|www4

-dynamic www5|www6

-</pre>

- </td>

- </tr>

- </table>

- <table border="0" cellspacing="1" cellpadding="5"

- bgcolor="#F0F0F0">

- <tr>

- <td>

-<pre>

-RewriteMap servers rnd:/path/to/file/map.txt

-</pre>

- </td>

- </tr>

- </table>

- </li>

- <li>

- Hash File

- MapType: <code>dbm</code>, MapSource: Unix filesystem

- path to valid regular file

- Here the source is a binary NDBM format file

- containing the same contents as a Plain Text

- format file, but in a special representation which is

- optimized for really fast lookups. You can create such a

- file with any NDBM tool or with the following Perl

- script:

- <table border="0" cellspacing="1" cellpadding="5"

- bgcolor="#F0F0F0">

- <tr>

- <td>

-<pre>

-#!/path/to/bin/perl

-##

-## txt2dbm -- convert txt map to dbm format

-##

-use NDBM_File;

-use Fcntl;

-($txtmap, $dbmmap) = @ARGV;

-open(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n";

-tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644) or die "Couldn't create $dbmmap!\n";

-while (<TXT>) {

- next if (/^\s*#/ or /^\s*$/);

- $DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/);

-untie %DB;

-close(TXT);

-</pre>

- </td>

- </tr>

- </table>

- <table border="0" cellspacing="1" cellpadding="5"

- bgcolor="#F0F0F0">

- <tr>

- <td>

-<pre>

-$ txt2dbm map.txt map.db

-</pre>

- </td>

- </tr>

- </table>

- </li>

- <li>

- Internal Function

- MapType: <code>int</code>, MapSource: Internal Apache

- function

- Here the source is an internal Apache function.

- Currently you cannot create your own, but the following

- functions already exists:

- <ul>

- <li>toupper:

- Converts the looked up key to all upper case.</li>

- <li>tolower:

- Converts the looked up key to all lower case.</li>

- <li>escape:

- Translates special characters in the looked up key to

- hex-encodings.</li>

- <li>unescape:

- Translates hex-encodings in the looked up key back to

- special characters.</li>

- </ul>

- </li>

- <li>

- External Rewriting Program

- MapType: <code>prg</code>, MapSource: Unix filesystem

- path to valid regular file

- Here the source is a program, not a map file. To

- create it you can use the language of your choice, but

- the result has to be a executable (i.e., either

- object-code or a script with the magic cookie trick

- '<code>#!/path/to/interpreter</code>' as the first

- line).

- This program is started once at startup of the Apache

- servers and then communicates with the rewriting engine

- over 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 (i.e., there

- is no corresponding value for the given key). A trivial

- program which will implement a 1:1 map (i.e.,

- key == value) could be:

- <table border="0" cellspacing="1" cellpadding="5"

- bgcolor="#F0F0F0">

- <tr>

- <td>

-<pre>

-#!/usr/bin/perl

-$| = 1;

-while (<STDIN>) {

- # ...put here any transformations or lookups...

- print $_;

-</pre>

- </td>

- </tr>

- </table>

- But be very careful:

-

- <ol>

- <li>``Keep it simple, stupid'' (KISS), because

- if this program hangs it will hang the Apache server

- when the rule occurs.</li>

- <li>Avoid one common mistake: never do buffered I/O on

- <code>stdout</code>! This will cause a deadloop! Hence

- the ``<code>$|=1</code>'' in the above example...</li>

- <li>Use the <samp>RewriteLock</samp> directive to

- define a lockfile mod_rewrite can use to synchronize

- the communication to the program. By default no such

- synchronization takes place.</li>

- </ol>

- </li>

- </ul>

- The <code>RewriteMap</code> directive can occur more than

- once. For each mapping-function use one

- <code>RewriteMap</code> directive to declare its rewriting

- mapfile. While you cannot declare a map in

- per-directory context it is of course possible to

- use this map in per-directory context.

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>Note: 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 every request.

- This is no problem, because the external lookup only

- happens once!</td>

- </tr>

- </table>

- <hr noshade="noshade" size="1" />

- <h3><a id="RewriteBase"

- name="RewriteBase">RewriteBase</a></h3>

- <a href="directive-dict.html#Syntax"

- rel="Help">Syntax:</a> RewriteBase

- URL-path

- <a href="directive-dict.html#Default"

- rel="Help">Default:</a> default is the

- physical directory path

- <a href="directive-dict.html#Context"

- rel="Help">Context:</a> directory,

- .htaccess

- <a href="directive-dict.html#Override"

- rel="Help">Override:</a>

- FileInfo

- <a href="directive-dict.html#Status"

- rel="Help">Status:</a> Extension

- <a href="directive-dict.html#Module"

- rel="Help">Module:</a> mod_rewrite.c

- <a href="directive-dict.html#Compatibility"

- rel="Help">Compatibility:</a> Apache

- 1.2

- The <code>RewriteBase</code> directive explicitly sets the

- base URL for per-directory rewrites. As you will see below,

- <code>RewriteRule</code> can be used in per-directory config

- files (<code>.htaccess</code>). There it will act locally,

- i.e., the local directory prefix is stripped at this

- stage of processing and your rewriting rules act only on the

- remainder. At the end it is automatically added back to the

- path.

- When a substitution occurs for a new URL, this module has

- to re-inject the URL into the server processing. To be able

- to do this it needs to know what the corresponding URL-prefix

- or URL-base is. By default this prefix is the corresponding

- filepath itself. But at most websites URLs are NOT

- directly related to physical filename paths, so this

- assumption will usually be wrong! There you have to

- use the <code>RewriteBase</code> directive to specify the

- correct URL-prefix.

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>Notice: If your webserver's URLs are

- not directly related to physical file

- paths, you have to use <code>RewriteBase</code> in every

- <code>.htaccess</code> files where you want to use

- <code>RewriteRule</code> directives.</td>

- </tr>

- </table>

- Example:

- <blockquote>

- Assume the following per-directory config file:

- <table border="0" cellspacing="1" cellpadding="5"

- bgcolor="#F0F0F0">

- <tr>

- <td>

-<pre>

-# /abc/def/.htaccess -- per-dir config file for directory /abc/def

-# Remember: /abc/def is the physical path of /xyz, i.e., the server

-# has a 'Alias /xyz /abc/def' directive e.g.

-RewriteEngine On

-# let the server know that we were reached via /xyz and not

-# via the physical path prefix /abc/def

-RewriteBase /xyz

-# now the rewriting rules

-RewriteRule ^oldstuff\.html$ newstuff.html

-</pre>

- </td>

- </tr>

- </table>

- In the above example, a request to

- <code>/xyz/oldstuff.html</code> gets correctly rewritten to

- the physical file <code>/abc/def/newstuff.html</code>.

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>

- Note - For Apache

- hackers:

- The following list gives detailed information about

- the internal processing steps:

-<pre>

-Request:

- /xyz/oldstuff.html

-Internal Processing:

- /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias)

- /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule)

- /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase)

- /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias)

-Result:

- /abc/def/newstuff.html

-

-</pre>

- This seems very complicated but is

- the correct Apache internal processing, because the

- per-directory rewriting comes too late in the

- process. So, when it occurs the (rewritten) request

- has to be re-injected into the Apache kernel! BUT:

- While this seems like a serious overhead, it really

- isn't, because this re-injection happens fully

- internally to the Apache server and the same

- procedure is used by many other operations inside

- Apache. So, you can be sure the design and

- implementation is correct.

- </td>

- </tr>

- </table>

- </blockquote>

- <hr noshade="noshade" size="1" />

- <h3><a id="RewriteCond"

- name="RewriteCond">RewriteCond</a></h3>

- <a href="directive-dict.html#Syntax"

- rel="Help">Syntax:</a> RewriteCond

- TestString CondPattern

- <a href="directive-dict.html#Default"

- rel="Help">Default:</a> None

- <a href="directive-dict.html#Context"

- rel="Help">Context:</a> server config,

- virtual host, directory, .htaccess

- <a href="directive-dict.html#Override"

- rel="Help">Override:</a>

- FileInfo

- <a href="directive-dict.html#Status"

- rel="Help">Status:</a> Extension

- <a href="directive-dict.html#Module"

- rel="Help">Module:</a> mod_rewrite.c

- <a href="directive-dict.html#Compatibility"

- rel="Help">Compatibility:</a> Apache 1.2

- (partially), Apache 1.3

- The <code>RewriteCond</code> directive defines a rule

- condition. Precede a <code>RewriteRule</code> directive with

- one or more <code>RewriteCond</code> directives. The

- following rewriting rule is only used if its pattern matches

- the current state of the URI and if these

- additional conditions apply too.

- TestString is a string which can contains the

- following expanded constructs in addition to plain text:

- <ul>

- <li>

- RewriteRule backreferences: These are

- backreferences of the form

- <blockquote>

- <code>$N</code>

- </blockquote>

- (0 <= N <= 9) which provide access to the grouped

- parts (parenthesis!) of the pattern from the

- corresponding <code>RewriteRule</code> directive (the one

- following the current bunch of <code>RewriteCond</code>

- directives).

- </li>

- <li>

- RewriteCond backreferences: These are

- backreferences of the form

- <blockquote>

- <code>%N</code>

- </blockquote>

- (1 <= N <= 9) which provide access to the grouped

- parts (parentheses!) of the pattern from the last matched

- <code>RewriteCond</code> directive in the current bunch

- of conditions.

- </li>

- <li>

- RewriteMap expansions: These are

- expansions of the form

- <blockquote>

- <code>${mapname:key|default}</code>

- </blockquote>

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

- RewriteMap</a> for more details.

- </li>

- <li>

- Server-Variables: These are variables of

- the form

- <blockquote>

- <code>%{</code> NAME_OF_VARIABLE

- <code>}</code>

- </blockquote>

- where NAME_OF_VARIABLE can be a string taken

- from the following list:

- <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5">

- <tr>

- <td valign="TOP">

- HTTP headers:

- HTTP_USER_AGENT

- HTTP_REFERER

- HTTP_COOKIE

- HTTP_FORWARDED

- HTTP_HOST

- HTTP_PROXY_CONNECTION

- HTTP_ACCEPT

-

- </td>

- <td valign="TOP">

- connection & request:

- REMOTE_ADDR

- REMOTE_HOST

- REMOTE_USER

- REMOTE_IDENT

- REQUEST_METHOD

- SCRIPT_FILENAME

- PATH_INFO

- QUERY_STRING

- AUTH_TYPE

-

- </td>

- </tr>

- <tr>

- <td valign="TOP">

- server internals:

- DOCUMENT_ROOT

- SERVER_ADMIN

- SERVER_NAME

- SERVER_ADDR

- SERVER_PORT

- SERVER_PROTOCOL

- SERVER_SOFTWARE

-

- </td>

- <td valign="TOP">

- system stuff:

- TIME_YEAR

- TIME_MON

- TIME_DAY

- TIME_HOUR

- TIME_MIN

- TIME_SEC

- TIME_WDAY

- TIME

-

- </td>

- <td valign="TOP">

- specials:

- API_VERSION

- THE_REQUEST

- REQUEST_URI

- REQUEST_FILENAME

- IS_SUBREQ

-

- </td>

- </tr>

- </table>

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>

- Notice: These variables all

- correspond to the similarly named HTTP

- MIME-headers, C variables of the Apache server or

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

- Most are documented elsewhere in the Manual or in

- the CGI specification. Those that are special to

- mod_rewrite include:

- <dl>

- <dt><code>IS_SUBREQ</code></dt>

- <dd>Will contain the text "true" if the request

- currently being processed is a sub-request,

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

- by modules that need to resolve additional files

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

- <dt><code>API_VERSION</code></dt>

- <dd>This is the version of the Apache module API

- (the internal interface between server and

- module) in the current httpd build, as defined in

- include/ap_mmn.h. The module API version

- corresponds to the version of Apache in use (in

- the release version of Apache 1.3.14, for

- instance, it is 19990320:10), but is mainly of

- interest to module authors.</dd>

- <dt><code>THE_REQUEST</code></dt>

- <dd>The full HTTP request line sent by the

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

- /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. (In the example above, this would be

- "/index.html".)</dd>

- <dt><code>REQUEST_FILENAME</code></dt>

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

- script matching the request.</dd>

- </dl>

- </td>

- </tr>

- </table>

- </li>

- </ul>

- Special Notes:

- <ol>

- <li>The variables SCRIPT_FILENAME and REQUEST_FILENAME

- contain the same value, i.e., the value of the

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

- <code>request_rec</code> structure of the Apache server.

- The first name is just the commonly known CGI variable name

- while the second is the consistent counterpart to

- REQUEST_URI (which contains the value of the

- <code>uri</code> field of <code>request_rec</code>).</li>

- <li>There is the special format:

- <code>%{ENV:variable}</code> where variable can be

- any environment variable. This is looked-up via internal

- Apache structures and (if not found there) via

- <code>getenv()</code> from the Apache server process.</li>

- <li>There is the special format:

- <code>%{HTTP:header}</code> where header can be

- any HTTP MIME-header name. This is looked-up from the HTTP

- request. Example: <code>%{HTTP:Proxy-Connection}</code> is

- the value of the HTTP header

- ``<code>Proxy-Connection:</code>''.</li>

- <li>There is the special format

- <code>%{LA-U:variable}</code> for look-aheads which perform

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

- value of variable. Use this when you want to use a

- variable for rewriting which is actually set later in an

- API phase and thus is not available at the current stage.

- For instance when you want to rewrite according to the

- <code>REMOTE_USER</code> variable from within the

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

- to use <code>%{LA-U:REMOTE_USER}</code> because this

- variable is set by the authorization phases which come

- after the URL translation phase where mod_rewrite

- operates. On the other hand, because mod_rewrite implements

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

- the Fixup phase of the API and because the authorization

- phases come before this phase, you just can use

- <code>%{REMOTE_USER}</code> there.</li>

- <li>There is the special format:

- <code>%{LA-F:variable}</code> which performs an internal

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

- of variable. Most of the time this is the same as

- LA-U above.</li>

- </ol>

- CondPattern is the condition pattern,

- i.e., a regular expression which is applied to the

- current instance of the TestString, i.e.,

- TestString is evaluated and then matched against

- CondPattern.

- Remember: CondPattern is a

- standard Extended Regular Expression with some

- additions:

- <ol>

- <li>You can prefix the pattern string with a

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

- non-matching pattern.</li>

- <li>

- There are some special variants of CondPatterns.

- Instead of real regular expression strings you can also

- use one of the following:

- <ul>

- <li>'<CondPattern' (is lexically

- lower)

- Treats the CondPattern as a plain string and

- compares it lexically to TestString. True if

- TestString is lexically lower than

- CondPattern.</li>

- <li>'>CondPattern' (is lexically

- greater)

- Treats the CondPattern as a plain string and

- compares it lexically to TestString. True if

- TestString is lexically greater than

- CondPattern.</li>

- <li>'=CondPattern' (is lexically

- equal)

- Treats the CondPattern as a plain string and

- compares it lexically to TestString. True if

- TestString is lexically equal to

- CondPattern, i.e the two strings are exactly

- equal (character by character). If CondPattern

- is just <samp>""</samp> (two quotation marks) this

- compares TestString to the empty string.</li>

- <li>'-d' (is

- directory)

- Treats the TestString as a pathname and tests

- if it exists and is a directory.</li>

- <li>'-f' (is regular

- file)

- Treats the TestString as a pathname and tests

- if it exists and is a regular file.</li>

- <li>'-s' (is regular file with

- size)

- Treats the TestString as a pathname and tests

- if it exists and is a regular file with size greater

- than zero.</li>

- <li>'-l' (is symbolic

- link)

- Treats the TestString as a pathname and tests

- if it exists and is a symbolic link.</li>

- <li>'-F' (is existing file via

- subrequest)

- Checks if TestString is a valid file and

- accessible via all the server's currently-configured

- access controls for that path. This uses an internal

- subrequest to determine the check, so use it with care

- because it decreases your servers performance!</li>

- <li>'-U' (is existing URL via

- subrequest)

- Checks if TestString is a valid URL and

- accessible via all the server's currently-configured

- access controls for that path. This uses an internal

- subrequest to determine the check, so use it with care

- because it decreases your server's performance!</li>

- </ul>

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>Notice: All of these tests can

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

- negate their meaning.</td>

- </tr>

- </table>

- </li>

- </ol>

- Additionally you can set special flags for

- CondPattern by appending

- <blockquote>

- <code>[</code>flags<code>]</code>

- </blockquote>

- as the third argument to the <code>RewriteCond</code>

- directive. Flags is a comma-separated list of the

- following flags:

- <ul>

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

- (no case)

- This makes the test case-insensitive, i.e., there

- is no difference between 'A-Z' and 'a-z' both in the

- expanded TestString and the CondPattern.

- This flag is effective only for comparisons between

- TestString and CondPattern. It has no

- effect on filesystem and subrequest checks.</li>

- <li>

- '<code>ornext|OR</code>'

- (or next condition)

- Use this to combine rule conditions with a local OR

- instead of the implicit AND. Typical example:

- <blockquote>

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

- </blockquote>

- Without this flag you would have to write the cond/rule

- three times.

- </li>

- </ul>

- Example:

- <blockquote>

- To rewrite the Homepage of a site according to the

- ``<code>User-Agent:</code>'' header of the request, you can

- use the following:

- <blockquote>

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

- </blockquote>

- Interpretation: If you use Netscape Navigator as your

- browser (which identifies itself as 'Mozilla'), then you

- get the max homepage, which includes Frames, etc.

- If you use the Lynx browser (which is Terminal-based), then

- you get the min homepage, which contains no images, no

- tables, etc. If you use any other browser you get

- the standard homepage.

- </blockquote>

- <hr noshade="noshade" size="1" />

- <h3><a id="RewriteRule"

- name="RewriteRule">RewriteRule</a></h3>

- <a href="directive-dict.html#Syntax"

- rel="Help">Syntax:</a> RewriteRule

- Pattern Substitution

- <a href="directive-dict.html#Default"

- rel="Help">Default:</a> None

- <a href="directive-dict.html#Context"

- rel="Help">Context:</a> server config,

- virtual host, directory, .htaccess

- <a href="directive-dict.html#Override"

- rel="Help">Override:</a>

- FileInfo

- <a href="directive-dict.html#Status"

- rel="Help">Status:</a> Extension

- <a href="directive-dict.html#Module"

- rel="Help">Module:</a> mod_rewrite.c

- <a href="directive-dict.html#Compatibility"

- rel="Help">Compatibility:</a> Apache 1.2

- (partially), Apache 1.3

- The <code>RewriteRule</code> directive is the real

- rewriting workhorse. The directive can occur more than once.

- Each directive then defines one single rewriting rule. The

- definition order of these rules is

- important, because this order is used when

- applying the rules at run-time.

- <a id="patterns" name="patterns">Pattern</a> can

- be (for Apache 1.1.x a System V8 and for Apache 1.2.x and

- later a POSIX) <a id="regexp" name="regexp">regular

- expression</a> which gets applied to the current URL. Here

- ``current'' means the value of the URL when this rule gets

- applied. This may not be the originally requested URL,

- because any number of rules may already

- have matched and made alterations to it.

- Some hints about the syntax of regular expressions:

- <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5">

- <tr>

- <td valign="TOP">

-<pre>

-Text:

- <code>.</code> Any single character

- <code>[</code>chars<code>]</code> Character class: One of chars

- <code>[^</code>chars<code>]</code> Character class: None of chars

- text1<code>|</code>text2 Alternative: text1 or text2

-Quantifiers:

- <code>?</code> 0 or 1 of the preceding text

- <code>*</code> 0 or N of the preceding text (N > 0)

- <code>+</code> 1 or N of the preceding text (N > 1)

-Grouping:

- <code>(</code>text<code>)</code> Grouping of text

- (either to set the borders of an alternative or

- for making backreferences where the Nth group can

- be used on the RHS of a RewriteRule with <code>$</code>N)

-Anchors:

- <code>^</code> Start of line anchor

- <code>$</code> End of line anchor

-Escaping:

- <code>\</code>char escape that particular char

- (for instance to specify the chars "<code>.[]()</code>" etc.)

-</pre>

- </td>

- </tr>

- </table>

- For more information about regular expressions either have

- a look at your local regex(3) manpage or its

- <code>src/regex/regex.3</code> copy in the Apache 1.3

- distribution. If you are interested in more detailed

- information about regular expressions and their variants

- (POSIX regex, Perl regex, etc.) have a look at the

- following dedicated book on this topic:

- <blockquote>

- Mastering Regular Expressions

- Jeffrey E.F. Friedl

- Nutshell Handbook Series

- O'Reilly & Associates, Inc. 1997

- ISBN 1-56592-257-3

- </blockquote>

- Additionally in mod_rewrite the NOT character

- ('<code>!</code>') is a possible pattern prefix. This gives

- you the ability to negate a pattern; to say, for instance:

- ``if the current URL does NOT match this

- pattern''. This can be used for exceptional cases, where

- it is easier to match the negative pattern, or as a last

- default rule.

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>Notice: When using the NOT character

- to negate a pattern you cannot have grouped wildcard

- parts in the pattern. This is impossible because when the

- pattern does NOT match, there are no contents for the

- groups. In consequence, if negated patterns are used, you

- cannot use <code>$N</code> in the substitution

- string!</td>

- </tr>

- </table>

- <a id="rhs" name="rhs">Substitution</a> of a

- rewriting rule is the string which is substituted for (or

- replaces) the original URL for which Pattern

- matched. Beside plain text you can use

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

- Back-references are <code>$</code>N

- (N=0..9) identifiers which will be replaced

- by the contents of the Nth group of the

- matched Pattern. The server-variables are the same

- as for the TestString 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 of

- the above list.

- As already mentioned above, all the rewriting rules are

- applied to the Substitution (in the order of

- definition in the config file). The URL is completely

- replaced by the Substitution and the

- rewriting process goes on until there are no more rules

- unless explicitly terminated by a

- <code>L</code> flag - see below.

- There is a special substitution string named

- '<code>-</code>' which means: NO

- substitution! Sounds silly? No, it is useful to

- provide rewriting rules which only match

- some URLs but do no substitution, e.g., in

- conjunction with the C (chain) flag to be

- able to have more than one pattern to be applied before a

- substitution occurs.

- One more note: You can even create URLs in the

- substitution string containing a query string part. Just use

- a question mark inside the substitution string to indicate

- that the following stuff should be re-injected into the

- QUERY_STRING. When you want to erase an existing query

- string, end the substitution string with just the question

- mark.

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>Note: There is a special feature:

- When you prefix a substitution field with

- <code>http://</code>thishost[:thisport]

- then mod_rewrite automatically strips it

- out. This auto-reduction on implicit external redirect

- URLs is a useful and important feature when used in

- combination with a mapping-function which generates the

- hostname part. Have a look at the first example in the

- example section below to understand this.</td>

- </tr>

- </table>

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>Remember: An unconditional external

- redirect to your own server will not work with the prefix

- <code>http://thishost</code> because of this feature. To

- achieve such a self-redirect, you have to use the

- R-flag (see below).</td>

- </tr>

- </table>

- Additionally you can set special flags for

- Substitution by appending

- <blockquote>

- <code>[</code>flags<code>]</code>

- </blockquote>

- as the third argument to the <code>RewriteRule</code>

- directive. Flags is a comma-separated list of the

- following flags:

- <ul>

- <li>

- '<code>redirect|R</code>

- [=code]' (force <a id="redirect"

- name="redirect">redirect</a>)

- Prefix Substitution with

- <code>http://thishost[:thisport]/</code> (which makes the

- new URL a URI) to force a external redirection. If no

- code is given a HTTP response of 302 (MOVED

- TEMPORARILY) is used. If you want to use other response

- codes in the range 300-400 just specify them as a number

- or use one of the following symbolic names:

- <code>temp</code> (default), <code>permanent</code>,

- <code>seeother</code>. Use it for rules which should

- canonicalize the URL and give it back to the client,

- e.g., translate ``<code>/~</code>'' into

- ``<code>/u/</code>'' or always append a slash to

- <code>/u/</code>user, etc.

- Note: When you use this flag, make

- sure that the substitution field is a valid URL! If not,

- you are redirecting to an invalid location! And remember

- that this flag itself only prefixes the URL with

- <code>http://thishost[:thisport]/</code>, rewriting

- continues. Usually you also want to stop and do the

- redirection immediately. To stop the rewriting you also

- have to provide the 'L' flag.

- </li>

- <li>'<code>forbidden|F</code>' (force URL

- to be forbidden)

- This forces the current URL to be forbidden,

- i.e., it immediately sends back a HTTP response of

- 403 (FORBIDDEN). Use this flag in conjunction with

- appropriate RewriteConds to conditionally block some

- URLs.</li>

- <li>'<code>gone|G</code>' (force URL to be

- gone)

- This forces the current URL to be gone, i.e., it

- immediately sends back a HTTP response of 410 (GONE). Use

- this flag to mark pages which no longer exist as gone.</li>

- <li>

- '<code>proxy|P</code>' (force

- proxy)

- This flag forces the substitution part to be internally

- forced as a proxy request and immediately (i.e.,

- rewriting rule processing stops here) put through the <a

- href="mod_proxy.html">proxy module</a>. You have to make

- sure that the substitution string is a valid URI

- (e.g., typically starting with

- <code>http://</code>hostname) which can be

- handled by the Apache proxy module. If not you 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 some remote stuff into the namespace of the local

- server.

- Notice: To use this functionality make sure you have

- the proxy module compiled into your Apache server

- program. If you don't know please check whether

- <code>mod_proxy.c</code> is part of the ``<code>httpd

- -l</code>'' output. If yes, this functionality is

- available to mod_rewrite. If not, then you first have to

- rebuild the ``<code>httpd</code>'' program with mod_proxy

- enabled.

- </li>

- <li>'<code>last|L</code>'

- (last rule)

- Stop the rewriting process here and don't apply any more

- rewriting rules. This corresponds to the Perl

- <code>last</code> command or the <code>break</code> command

- from the C language. Use this flag to prevent the currently

- rewritten URL from being rewritten further by following

- rules. For example, use it to rewrite the root-path URL

- ('<code>/</code>') to a real one, e.g.,

- '<code>/e/www/</code>'.</li>

- <li>'<code>next|N</code>'

- (next round)

- Re-run the rewriting process (starting again with the

- first rewriting rule). Here the URL to match is again not

- the original URL but the URL from the last rewriting rule.

- This corresponds to the Perl <code>next</code> command or

- the <code>continue</code> command from the C language. Use

- this flag to restart the rewriting process, i.e.,

- to immediately go to the top of the loop.

- But be careful not to create an infinite

- loop!</li>

- <li>'<code>chain|C</code>'

- (chained with next rule)

- This flag chains the current rule with the next rule

- (which itself can be chained with the following rule,

- etc.). This has the following effect: if a rule

- matches, then processing continues as usual, i.e.,

- the flag has no effect. If the rule does

- not match, then all following chained

- rules are skipped. For instance, use it 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 to occur!).</li>

- <li>

- '<code>type|T</code>=MIME-type'

- (force MIME type)

- Force the MIME-type of the target file to be

- MIME-type. For instance, this can be used to

- simulate the <code>mod_alias</code> directive

- <code>ScriptAlias</code> which internally forces all files

- inside the mapped directory to have a MIME type of

- ``<code>application/x-httpd-cgi</code>''.</li>

- <li>

- '<code>nosubreq|NS</code>' (used only if

- no internal

- sub-request)

- 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 <code>mod_include</code> tries to find out

- information about possible directory default files

- (<code>index.xxx</code>). On sub-requests it is not

- always useful and even sometimes causes a failure to if

- the complete set of rules are applied. Use this flag to

- exclude some rules.

- Use the following rule for your decision: whenever you

- prefix some URLs with CGI-scripts to force them to be

- processed by the CGI-script, the chance is high that you

- will run into problems (or even overhead) on

- sub-requests. In these cases, use this flag.

- </li>

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

- (no case)

- This makes the Pattern case-insensitive,

- i.e., there is no difference between 'A-Z' and

- 'a-z' when Pattern is matched against the current

- URL.</li>

- <li>'<code>qsappend|QSA</code>'

- (query string

- append)

- This flag forces the rewriting engine to append a query

- string part in the substitution string to the existing one

- instead of replacing it. Use this when you want to add more

- data to the query string via a rewrite rule.</li>

- <li>

- '<code>noescape|NE</code>'

- (no URI escaping of

- output)

- This flag keeps 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 being done. This allows percent symbols to appear in

- the output, as in

-<pre>

- RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]

-</pre>

- which would turn '<code>/foo/zed</code>' into a safe

- request for '<code>/bar?arg=P1=zed</code>'.

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>Notice: The

- <code>noescape</code> flag is only available with

- Apache 1.3.20 and later versions.</td>

- </tr>

- </table>

- </li>

- <li>

- '<code>passthrough|PT</code>'

- (pass through to next

- handler)

- This flag forces the rewriting 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

- be able to post-process the output of

- <code>RewriteRule</code> directives by

- <code>Alias</code>, <code>ScriptAlias</code>,

- <code>Redirect</code>, etc. directives from

- other URI-to-filename translators. A trivial example to

- show the semantics: If you want to rewrite

- <code>/abc</code> to <code>/def</code> via the rewriting

- engine of <code>mod_rewrite</code> and then

- <code>/def</code> to <code>/ghi</code> with

- <code>mod_alias</code>:

-<pre>

- RewriteRule ^/abc(.*) /def$1 [PT]

- Alias /def /ghi

-</pre>

- If you omit the <code>PT</code> flag then

- <code>mod_rewrite</code> will do its job fine,

- i.e., it rewrites <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> comes and tries to do a

- URI-to-filename transition which will not work.

- Note: You have to use this flag if you want to

- intermix directives of different modules which contain

- URL-to-filename translators. The typical example

- is the use of <code>mod_alias</code> and

- <code>mod_rewrite</code>..

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>Note - For Apache

- hackers:

- If the current Apache API had a filename-to-filename

- hook additionally to the URI-to-filename hook then we

- wouldn't need this flag! But without such a hook this

- flag is the only solution. The Apache Group has

- discussed this problem and will add such a hook in

- Apache version 2.0. </td>

- </tr>

- </table>

- </li>

- <li>'<code>skip|S</code>=num'

- (skip next rule(s))

- This flag forces the rewriting engine to skip the next

- num rules in sequence when 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 not the same as the

- 'chain|C' flag!)</li>

- <li>

- '<code>env|E=</code>VAR:VAL'

- (set environment variable)

- This forces an environment variable named VAR to

- be set to the value VAL, where VAL 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 be later dereferenced in many situations, but

- usually from within XSSI (via <code><!--#echo

- var="VAR"--></code>) or CGI (e.g.

- <code>$ENV{'VAR'}</code>). Additionally you can dereference

- it in a following RewriteCond pattern via

- <code>%{ENV:VAR}</code>. Use this to strip but remember

- information from URLs.</li>

- </ul>

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>

- Note: Never forget that

- Pattern is applied to a complete URL in

- per-server configuration files. But in

- per-directory configuration files, the per-directory

- prefix (which always is the same for a specific

- directory!) is automatically removed for the

- pattern matching and automatically added after

- the substitution has been done. This feature

- is essential for many sorts of rewriting, because

- without this prefix stripping you 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 not be added and an

- external redirect or proxy throughput (if flag

- P is used!) is forced!

- </td>

- </tr>

- </table>

- <table width="70%" border="0" bgcolor="#E0E0F0"

- cellspacing="0" cellpadding="10">

- <tr>

- <td>Note: To enable the rewriting engine

- for per-directory configuration files you need to set

- ``<code>RewriteEngine On</code>'' in these files

- and ``<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 rewriting engine. This restriction is

- needed for security reasons.</td>

- </tr>

- </table>

- Here are all possible substitution combinations and their

- meanings:

- Inside per-server configuration

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

- for request ``<code>GET

- /somepath/pathinfo</code>'':

-

- <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5">

- <tr>

- <td>

-<pre>

-Given Rule Resulting Substitution

----------------------------------------------- ----------------------------------

-^/somepath(.*) otherpath$1 not supported, because invalid!

-^/somepath(.*) otherpath$1 [R] not supported, because invalid!

-^/somepath(.*) otherpath$1 [P] not supported, because invalid!

----------------------------------------------- ----------------------------------

-^/somepath(.*) /otherpath$1 /otherpath/pathinfo

-^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo

- via external redirection

-^/somepath(.*) /otherpath$1 [P] not supported, because silly!

----------------------------------------------- ----------------------------------

-^/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] not supported, because silly!

----------------------------------------------- ----------------------------------

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

- </td>

- </tr>

- </table>

- Inside per-directory configuration for

- <code>/somepath</code>

- (i.e., file <code>.htaccess</code> in dir

- <code>/physical/path/to/somepath</code> containing

- <code>RewriteBase /somepath</code>)

- for request ``<code>GET

- /somepath/localpath/pathinfo</code>'':

-

- <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5">

- <tr>

- <td>

-<pre>

-Given Rule Resulting Substitution

----------------------------------------------- ----------------------------------

-^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo

-^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo

- via external redirection

-^localpath(.*) otherpath$1 [P] not supported, because silly!

----------------------------------------------- ----------------------------------

-^localpath(.*) /otherpath$1 /otherpath/pathinfo

-^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo

- via external redirection

-^localpath(.*) /otherpath$1 [P] not supported, because silly!

----------------------------------------------- ----------------------------------

-^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] not supported, because silly!

----------------------------------------------- ----------------------------------

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

- </td>

- </tr>

- </table>

- Example:

- <blockquote>

- We want to rewrite URLs of the form

- <blockquote>

- <code>/</code> Language <code>/~</code>

- Realname <code>/.../</code> File

- </blockquote>

- into

- <blockquote>

- <code>/u/</code> Username <code>/.../</code>

- File <code>.</code> Language

- </blockquote>

- We take the rewrite mapfile from above and save it under

- <code>/path/to/file/map.txt</code>. Then we only have to

- add the following lines to the Apache server configuration

- file:

- <blockquote>

-<pre>

-RewriteLog /path/to/file/rewrite.log

-RewriteMap real-to-user txt:/path/to/file/map.txt

-RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1

-</pre>

- </blockquote>

- <hr noshade="noshade" size="1" />

- <center>

- <h1><a id="Miscelleneous"

- name="Miscelleneous">Miscellaneous</a></h1>

- </center>

- <hr noshade="noshade" size="1" />

- <h2><a id="EnvVar" name="EnvVar">Environment

- Variables</a></h2>

- This module keeps track of two additional (non-standard)

- CGI/SSI environment variables named <code>SCRIPT_URL</code>

- and <code>SCRIPT_URI</code>. These contain the

- logical Web-view to the current resource, while the

- standard CGI/SSI variables <code>SCRIPT_NAME</code> and

- <code>SCRIPT_FILENAME</code> contain the physical

- System-view.

- Notice: These variables hold the URI/URL as they were

- initially requested, i.e., before any

- rewriting. This is important because the rewriting process is

- primarily used to rewrite logical URLs to physical

- pathnames.

- Example:

- <blockquote>

-<pre>

-SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html

-SCRIPT_FILENAME=/u/rse/.www/index.html

-SCRIPT_URL=/u/rse/

-SCRIPT_URI=http://en1.engelschall.com/u/rse/

-</pre>

- </blockquote>

- <hr noshade="noshade" size="1" />

- <h2><a id="Solutions" name="Solutions">Practical

- Solutions</a></h2>

- We also have an <a href="../misc/rewriteguide.html">URL

- Rewriting Guide</a> available, which provides a collection of

- practical solutions for URL-based problems. There you can

- find real-life rulesets and additional information about

- mod_rewrite.

- </blockquote>

- <hr />

- <h3 align="CENTER">Apache HTTP Server Version 1.3</h3>

- <a href="./"><img src="../images/index.gif" alt="Index" /></a>

- <a href="../"><img src="../images/home.gif" alt="Home" /></a>

-

-

- </body>

-</html>