You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by rb...@apache.org on 2011/03/18 14:37:22 UTC
svn commit: r1082915 [6/7] - /httpd/httpd/branches/2.2.x/docs/manual/rewrite/
Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.html.en?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.html.en (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.html.en Fri Mar 18 13:37:20 2011
@@ -0,0 +1,450 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ This file is generated from xml source: DO NOT EDIT
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ -->
+<title>Using RewriteMap - Apache HTTP Server</title>
+<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
+<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
+<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
+<link href="../images/favicon.ico" rel="shortcut icon" /></head>
+<body id="manual-page"><div id="page-header">
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
+<p class="apache">Apache HTTP Server Version 2.2</p>
+<img alt="" src="../images/feather.gif" /></div>
+<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
+<div id="path">
+<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.2</a> > <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Using RewriteMap</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/rewrite/rewritemap.html" title="English"> en </a></p>
+</div>
+
+
+ <p>This document supplements the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
+the use of the <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive,
+and provides examples of each of the various <code>RewriteMap</code> types.</p>
+
+ <div class="warning">Note that many of these examples won't work unchanged in your
+particular server configuration, so it's important that you understand
+them, rather than merely cutting and pasting the examples into your
+configuration.</div>
+
+ </div>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#rnd">rnd: Randomized Plain Text</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#dbm">dbm: DBM Hash File</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#int">int: Internal Function</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#prg">prg: External Rewriting Program</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#dbd">dbd or fastdbd: SQL Query</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#summary">Summary</a></li>
+</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="advanced.html">Advanced techniques and tricks</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="introduction" id="introduction">Introduction</a></h2>
+
+
+ <p>
+ The <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
+ defines an external function which can be called in the context of
+ <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or
+ <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directives to
+ perform rewriting that is too complicated, or too specialized to be
+ performed just by regular expressions. The source of this lookup can
+ be any of the types listed in the sections below, and enumerated in
+ the <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> reference
+ documentation.</p>
+
+ <p>The syntax of the <code>RewriteMap</code> directive is as
+ follows:</p>
+
+<div class="example"><p><code>
+RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
+</code></p></div>
+
+ <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
+ arbitray name that you assign to the map, and which you will use in
+ directives later on. Arguments are passed to the map via the
+ following syntax:</p>
+
+ <p class="indent">
+ <strong>
+ <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
+ <code>}</code> <br /> <code>${</code> <em>MapName</em> <code>:</code>
+ <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
+ </strong>
+ </p>
+
+ <p>When such a construct occurs, the map <em>MapName</em> is
+ consulted and the key <em>LookupKey</em> is looked-up. If the
+ key is found, the map-function construct is substituted by
+ <em>SubstValue</em>. If the key is not found then it is
+ substituted by <em>DefaultValue</em> or by the empty string
+ if no <em>DefaultValue</em> was specified.</p>
+
+ <p>For example, you might define a
+ <code class="directive">RewriteMap</code> as:</p>
+ <div class="example"><p><code>
+ RewriteMap examplemap txt:/path/to/file/map.txt
+ </code></p></div>
+ <p>You would then be able to use this map in a
+ <code class="directive">RewriteRule</code> as follows:</p>
+<div class="example"><p><code>
+ RewriteRule ^/ex/(.*) ${examplemap:$1}
+</code></p></div>
+
+<p>A default value can be specified in the event that nothing is found
+in the map:</p>
+
+<div class="example"><p><code>
+RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
+</code></p></div>
+
+<div class="note"><h3>Per-directory and .htaccess context</h3>
+<p>
+The <code>RewriteMap</code> directive may not be used in
+<Directory> sections or <code>.htaccess</code> files. You must
+declare the map in server or virtualhost context. You may use the map,
+once created, in your <code>RewriteRule</code> and
+<code>RewriteCond</code> directives in those scopes. You just can't
+<strong>declare</strong> it in those scopes.
+</p>
+</div>
+
+<p>The sections that follow describe the various <em>MapType</em>s that
+may be used, and give examples of each.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="txt" id="txt">txt: Plain text maps</a></h2>
+
+
+ <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
+ plain-text mapping file, containing space-separated key/value pair
+ per line. Optionally, a line may be contain a comment, starting with
+ a '#' character.</p>
+
+ <p>For example, the following might be valid entries in a map
+ file.</p>
+
+ <p class="indent">
+ # Comment line<br />
+ <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
+ <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
+ </p>
+
+ <p>When the RewriteMap is invoked the argument is looked for in the
+ first argument of a line, and, if found, the substitution value is
+ returned.</p>
+
+ <p>For example, we might use a mapfile to translate product names to
+ product IDs for easier-to-remember URLs, using the following
+ recipe:</p>
+
+ <div class="example"><h3>Product to ID configuration</h3><p><code>
+ RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
+ RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
+ </code></p></div>
+
+ <p>We assume here that the <code>prods.php</code> script knows what
+ to do when it received an argument of <code>id=NOTFOUND</code> when
+ a product is not found in the lookup map.</p>
+
+ <p>The file <code>/etc/apache2/productmap.txt</code> then contains
+ the following:</p>
+
+ <div class="example"><h3>Product to ID map</h3><p><code>
+##<br />
+## productmap.txt - Product to ID map file<br />
+##<br />
+<br />
+television 993<br />
+stereo 198<br />
+fishingrod 043<br />
+basketball 418<br />
+telephone 328
+ </code></p></div>
+
+ <p>Thus, when <code>http://example.com/product/television</code> is
+ requested, the <code>RewriteRule</code> is applied, and the request
+ is internally mapped to <code>/prods.php?id=993</code>.</p>
+
+ <div class="note"><h3>Note: .htaccess files</h3>
+ The example given is crafted to be used in server or virtualhost
+ scope. If you're planning to use this in a <code>.htaccess</code>
+ file, you'll need to remove the leading slash from the rewrite
+ pattern in order for it to match anything:
+ <div class="example"><p><code>
+ RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
+ </code></p></div>
+ </div>
+
+ <div class="note"><h3>Cached lookups</h3>
+ <p>
+ The looked-up keys are cached by httpd until the <code>mtime</code>
+ (modified time) of the mapfile changes, or the httpd server is
+ restarted. This ensures better performance on maps that are called
+ by many requests.
+ </p>
+ </div>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
+
+
+ <p>When a MapType of <code>rnd</code> is used, the MapSource is a
+ filesystem path to a plain-text mapping file, each line of which
+ contains a key, and one or more values separated by <code>|</code>.
+ One of these values will be chosen at random if the key is
+ matched.</p>
+
+ <p>For example, you might use the following map
+ file and directives to provide a random load balancing between
+ several back-end server, via a reverse-proxy. Images are sent
+ to one of the servers in the 'static' pool, while everything
+ else is sent to one of the 'dynamic' pool.</p>
+
+ <div class="example"><h3>Rewrite map file</h3><p><code>
+##<br />
+## map.txt -- rewriting map<br />
+##<br />
+<br />
+static www1|www2|www3|www4<br />
+dynamic www5|www6
+ </code></p></div>
+
+ <div class="example"><h3>Configuration directives</h3><p><code>
+ RewriteMap servers rnd:/path/to/file/map.txt<br />
+ <br />
+ RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br />
+ RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
+ </code></p></div>
+
+ <p>So, when an image is requested and the first of these rules is
+ matched, <code>RewriteMap</code> looks up the string
+ <code>static</code> in the map file, which returns one of the
+ specified hostnames at random, which is then used in the
+ <code>RewriteRule</code> target.</p>
+
+ <p>If you wanted to have one of the servers more likely to be chosen
+ (for example, if one of the server has more memory than the others,
+ and so can handle more requests) simply list it more times in the
+ map file.</p>
+
+ <div class="example"><p><code>
+static www1|www1|www2|www3|www4
+ </code></p></div>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="dbm" id="dbm">dbm: DBM Hash File</a></h2>
+
+
+ <p>When a MapType of <code>dbm</code> is used, the MapSource is a
+ filesystem path to a DBM database file containing key/value pairs to
+ be used in the mapping. This works exactly the same way as the
+ <code>txt</code> map, but is much faster, because a DBM is indexed,
+ whereas a text file is not. This allows more rapid access to the
+ desired key.</p>
+
+ <p>You may optionally specify a particular dbm type:</p>
+
+ <div class="example"><p><code>
+ RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
+ </code></p></div>
+
+ <p>The type can be sdbm, gdbm, ndbm or db.
+ However, it is recommended that you just use the <a href="../programs/httxt2dbm.html">httxt2dbm</a> utility that is
+ provided with Apache HTTP Server, as it will use the correct DBM library,
+ matching the one that was used when httpd itself was built.</p>
+
+ <p>To create a dbm file, first create a text map file as described
+ in the <a href="#txt">txt</a> section. Then run
+ <code>httxt2dbm</code>:</p>
+
+<div class="example"><p><code>
+$ httxt2dbm -i mapfile.txt -o mapfile.map
+</code></p></div>
+
+<p>You can then reference the resulting file in your
+<code>RewriteMap</code> directive:</p>
+
+<div class="example"><p><code>
+RewriteMap mapname dbm:/etc/apache/mapfile.map
+</code></p></div>
+
+<div class="note">
+<p>Note that with some dbm types, more than one file is generated, with
+a common base name. For example, you may have two files named
+<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
+normal, and you need only use the base name <code>mapfile.map</code> in
+your <code>RewriteMap</code> directive.</p>
+</div>
+
+<div class="note"><h3>Cached lookups</h3>
+<p>
+The looked-up keys are cached by httpd until the <code>mtime</code>
+(modified time) of the mapfile changes, or the httpd server is
+restarted. This ensures better performance on maps that are called
+by many requests.
+</p>
+</div>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="int" id="int">int: Internal Function</a></h2>
+
+
+ <p>When a MapType of <code>int</code> is used, the MapSource is one
+ of the available internal RewriteMap functions. Module authors can provide
+ additional internal functions by registering them with the
+ <code>ap_register_rewrite_mapfunc</code> API.
+ The functions that are provided by default are:
+ </p>
+
+ <ul>
+ <li><strong>toupper</strong>:<br />
+ Converts the key to all upper case.</li>
+ <li><strong>tolower</strong>:<br />
+ Converts the key to all lower case.</li>
+ <li><strong>escape</strong>:<br />
+ Translates special characters in the key to
+ hex-encodings.</li>
+ <li><strong>unescape</strong>:<br />
+ Translates hex-encodings in the key back to
+ special characters.</li>
+ </ul>
+
+ <p>
+ To use one of these functions, create a <code>RewriteMap</code> referencing
+ the int function, and then use that in your <code>RewriteRule</code>:
+ </p>
+
+ <div class="example"><h3>Redirect a URI to an all-lowercase version of itself</h3><p><code>
+ RewriteMap lc int:tolower<br />
+ RewriteRule (.*[A-Z]+.*) ${lc:$1} [R]
+ </code></p></div>
+
+ <div class="note">
+ <p>Please note that the example offered here is for
+ illustration purposes only, and is not a recommendation. If you want
+ to make URLs case-insensitive, consider using
+ <code class="module"><a href="../mod/mod_speling.html">mod_speling</a></code> instead.
+ </p>
+ </div>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="prg" id="prg">prg: External Rewriting Program</a></h2>
+
+ <p>When a MapType of <code>prg</code> is used, the MapSource is a
+ filesystem path to an executable program which will providing the
+ mapping behavior. This can be a compiled binary file, or a program
+ in an interpreted language such as Perl or Python.</p>
+
+ <p>This program is started once, when the Apache HTTP Server is
+ started, and then communicates with the rewriting engine via
+ <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
+ function lookup, it expects one argument via <code>STDIN</code>, and
+ should return one new-line terminated response string on
+ <code>STDOUT</code>. If there is no corresponding lookup value, the
+ map program should return the four-character string
+ "<code>NULL</code>" to indicate this.</p>
+
+ <p>External rewriting programs are not started if they're defined in
+ a context that does not have <code class="directive"><a href="../mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code> set to
+ <code>on</code>.</p>
+
+ <p>This feature utilizes the <code>rewrite-map</code> mutex,
+ which is required for reliable communication with the program.
+ The mutex mechanism and lock file can be configured with the
+ <code class="directive"><a href="../mod/core.html#mutex">Mutex</a></code> directive.</p>
+
+ <p>A simple example is shown here which will replace all dashes with
+ underscores in a request URI.</p>
+
+ <div class="example"><h3>Rewrite configuration</h3><p><code>
+ RewriteMap d2u prg:/www/bin/dash2under.pl<br />
+ RewriteRule - ${d2u:%{REQUEST_URI}}
+ </code></p></div>
+
+ <div class="example"><h3>dash2under.pl</h3><p><code>
+ #!/usr/bin/perl<br />
+ $| = 1; # Turn off I/O buffering<br />
+ while (<STDIN>) {<br />
+ <span class="indent">
+ s/-/_/g; # Replace dashes with underscores<br />
+ print $_;<br />
+ </span>
+ }<br />
+ </code></p></div>
+
+<div class="note"><h3>Caution!</h3>
+<ul>
+<li>Keep your rewrite map program as simple as possible. If the program
+hangs, it will cause httpd to wait indefinitely for a response from the
+map, which will, in turn, cause httpd to stop responding to
+requests.</li>
+<li>Be sure to turn off buffering in your program. In Perl this is done
+by the second line in the example script: <code>$| = 1;</code> This will
+of course vary in other languages. Buffered I/O will cause httpd to wait
+for the output, and so it will hang.</li>
+<li>Remember that there is only one copy of the program, started at
+server startup. All requests will need to go through this one bottleneck.
+This can cause significant slowdowns if many requests must go through
+this process, or if the script itself is very slow.</li>
+</ul>
+</div>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="dbd" id="dbd">dbd or fastdbd: SQL Query</a></h2>
+
+
+ <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
+ used, the MapSource is a SQL SELECT statement that takes a single
+ argument and returns a single value.</p>
+
+ <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> will need to be configured to point at
+ the right database for this statement to be executed.</p>
+
+ <p>There are two forms of this MapType.
+ Using a MapType of <code>dbd</code> causes the query to be
+ executed with each map request, while using <code>fastdbd</code>
+ caches the database lookups internally. So, while
+ <code>fastdbd</code> is more efficient, and therefore faster, it
+ won't pick up on changes to the database until the server is
+ restarted.</p>
+
+ <p>If a query returns more than one row, a random row from
+the result set is used.</p>
+
+ <div class="example"><h3>Example</h3><p><code>
+RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
+ </code></p></div>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="summary" id="summary">Summary</a></h2>
+
+
+ <p>The <code class="directive">RewriteMap</code> directive can occur more than
+ once. For each mapping-function use one
+ <code class="directive">RewriteMap</code> directive to declare its rewriting
+ mapfile.</p>
+
+ <p>While you cannot <strong>declare</strong> a map in
+ per-directory context (<code>.htaccess</code> files or
+ <Directory> blocks) it is possible to
+ <strong>use</strong> this map in per-directory context. </p>
+
+ </div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/rewritemap.html" title="English"> en </a></p>
+</div><div id="footer">
+<p class="apache">Copyright 2011 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
+</body></html>
\ No newline at end of file
Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml Fri Mar 18 13:37:20 2011
@@ -0,0 +1,445 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 882992 $ -->
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<manualpage metafile="rewritemap.xml.meta">
+ <parentdocument href="./">Rewrite</parentdocument>
+ <title>Using RewriteMap</title>
+ <summary>
+
+ <p>This document supplements the <module>mod_rewrite</module>
+<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
+the use of the <directive module="mod_rewrite">RewriteMap</directive> directive,
+and provides examples of each of the various <code>RewriteMap</code> types.</p>
+
+ <note type="warning">Note that many of these examples won't work unchanged in your
+particular server configuration, so it's important that you understand
+them, rather than merely cutting and pasting the examples into your
+configuration.</note>
+
+ </summary>
+ <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
+ <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
+ <seealso><a href="remapping.html">Redirection and remapping</a></seealso>
+ <seealso><a href="access.html">Controlling access</a></seealso>
+ <seealso><a href="vhosts.html">Virtual hosts</a></seealso>
+ <seealso><a href="proxy.html">Proxying</a></seealso>
+ <seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>
+ <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
+
+ <section id="introduction">
+ <title>Introduction</title>
+
+ <p>
+ The <directive module="mod_rewrite">RewriteMap</directive> directive
+ defines an external function which can be called in the context of
+ <directive module="mod_rewrite">RewriteRule</directive> or
+ <directive module="mod_rewrite">RewriteCond</directive> directives to
+ perform rewriting that is too complicated, or too specialized to be
+ performed just by regular expressions. The source of this lookup can
+ be any of the types listed in the sections below, and enumerated in
+ the <directive module="mod_rewrite">RewriteMap</directive> reference
+ documentation.</p>
+
+ <p>The syntax of the <code>RewriteMap</code> directive is as
+ follows:</p>
+
+<example>
+RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
+</example>
+
+ <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
+ arbitray name that you assign to the map, and which you will use in
+ directives later on. Arguments are passed to the map via the
+ following syntax:</p>
+
+ <p class="indent">
+ <strong>
+ <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
+ <code>}</code> <br/> <code>${</code> <em>MapName</em> <code>:</code>
+ <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
+ </strong>
+ </p>
+
+ <p>When such a construct occurs, the map <em>MapName</em> is
+ consulted and the key <em>LookupKey</em> is looked-up. If the
+ key is found, the map-function construct is substituted by
+ <em>SubstValue</em>. If the key is not found then it is
+ substituted by <em>DefaultValue</em> or by the empty string
+ if no <em>DefaultValue</em> was specified.</p>
+
+ <p>For example, you might define a
+ <directive>RewriteMap</directive> as:</p>
+ <example>
+ RewriteMap examplemap txt:/path/to/file/map.txt
+ </example>
+ <p>You would then be able to use this map in a
+ <directive>RewriteRule</directive> as follows:</p>
+<example>
+ RewriteRule ^/ex/(.*) ${examplemap:$1}
+</example>
+
+<p>A default value can be specified in the event that nothing is found
+in the map:</p>
+
+<example>
+RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
+</example>
+
+<note><title>Per-directory and .htaccess context</title>
+<p>
+The <code>RewriteMap</code> directive may not be used in
+<Directory> sections or <code>.htaccess</code> files. You must
+declare the map in server or virtualhost context. You may use the map,
+once created, in your <code>RewriteRule</code> and
+<code>RewriteCond</code> directives in those scopes. You just can't
+<strong>declare</strong> it in those scopes.
+</p>
+</note>
+
+<p>The sections that follow describe the various <em>MapType</em>s that
+may be used, and give examples of each.</p>
+ </section>
+
+ <section id="txt">
+ <title>txt: Plain text maps</title>
+
+ <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
+ plain-text mapping file, containing space-separated key/value pair
+ per line. Optionally, a line may be contain a comment, starting with
+ a '#' character.</p>
+
+ <p>For example, the following might be valid entries in a map
+ file.</p>
+
+ <p class="indent">
+ # Comment line<br />
+ <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
+ <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
+ </p>
+
+ <p>When the RewriteMap is invoked the argument is looked for in the
+ first argument of a line, and, if found, the substitution value is
+ returned.</p>
+
+ <p>For example, we might use a mapfile to translate product names to
+ product IDs for easier-to-remember URLs, using the following
+ recipe:</p>
+
+ <example><title>Product to ID configuration</title>
+ RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
+ RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
+ </example>
+
+ <p>We assume here that the <code>prods.php</code> script knows what
+ to do when it received an argument of <code>id=NOTFOUND</code> when
+ a product is not found in the lookup map.</p>
+
+ <p>The file <code>/etc/apache2/productmap.txt</code> then contains
+ the following:</p>
+
+ <example><title>Product to ID map</title>
+##<br />
+## productmap.txt - Product to ID map file<br />
+##<br />
+<br />
+television 993<br />
+stereo 198<br />
+fishingrod 043<br />
+basketball 418<br />
+telephone 328
+ </example>
+
+ <p>Thus, when <code>http://example.com/product/television</code> is
+ requested, the <code>RewriteRule</code> is applied, and the request
+ is internally mapped to <code>/prods.php?id=993</code>.</p>
+
+ <note><title>Note: .htaccess files</title>
+ The example given is crafted to be used in server or virtualhost
+ scope. If you're planning to use this in a <code>.htaccess</code>
+ file, you'll need to remove the leading slash from the rewrite
+ pattern in order for it to match anything:
+ <example>
+ RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
+ </example>
+ </note>
+
+ <note><title>Cached lookups</title>
+ <p>
+ The looked-up keys are cached by httpd until the <code>mtime</code>
+ (modified time) of the mapfile changes, or the httpd server is
+ restarted. This ensures better performance on maps that are called
+ by many requests.
+ </p>
+ </note>
+
+ </section>
+ <section id="rnd">
+ <title>rnd: Randomized Plain Text</title>
+
+ <p>When a MapType of <code>rnd</code> is used, the MapSource is a
+ filesystem path to a plain-text mapping file, each line of which
+ contains a key, and one or more values separated by <code>|</code>.
+ One of these values will be chosen at random if the key is
+ matched.</p>
+
+ <p>For example, you might use the following map
+ file and directives to provide a random load balancing between
+ several back-end server, via a reverse-proxy. Images are sent
+ to one of the servers in the 'static' pool, while everything
+ else is sent to one of the 'dynamic' pool.</p>
+
+ <example><title>Rewrite map file</title>
+##<br />
+## map.txt -- rewriting map<br />
+##<br />
+<br />
+static www1|www2|www3|www4<br />
+dynamic www5|www6
+ </example>
+
+ <example><title>Configuration directives</title>
+ RewriteMap servers rnd:/path/to/file/map.txt<br/>
+ <br/>
+ RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br/>
+ RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
+ </example>
+
+ <p>So, when an image is requested and the first of these rules is
+ matched, <code>RewriteMap</code> looks up the string
+ <code>static</code> in the map file, which returns one of the
+ specified hostnames at random, which is then used in the
+ <code>RewriteRule</code> target.</p>
+
+ <p>If you wanted to have one of the servers more likely to be chosen
+ (for example, if one of the server has more memory than the others,
+ and so can handle more requests) simply list it more times in the
+ map file.</p>
+
+ <example>
+static www1|www1|www2|www3|www4
+ </example>
+
+ </section>
+
+ <section id="dbm">
+ <title>dbm: DBM Hash File</title>
+
+ <p>When a MapType of <code>dbm</code> is used, the MapSource is a
+ filesystem path to a DBM database file containing key/value pairs to
+ be used in the mapping. This works exactly the same way as the
+ <code>txt</code> map, but is much faster, because a DBM is indexed,
+ whereas a text file is not. This allows more rapid access to the
+ desired key.</p>
+
+ <p>You may optionally specify a particular dbm type:</p>
+
+ <example>
+ RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
+ </example>
+
+ <p>The type can be sdbm, gdbm, ndbm or db.
+ However, it is recommended that you just use the <a
+ href="../programs/httxt2dbm.html">httxt2dbm</a> utility that is
+ provided with Apache HTTP Server, as it will use the correct DBM library,
+ matching the one that was used when httpd itself was built.</p>
+
+ <p>To create a dbm file, first create a text map file as described
+ in the <a href="#txt">txt</a> section. Then run
+ <code>httxt2dbm</code>:</p>
+
+<example>
+$ httxt2dbm -i mapfile.txt -o mapfile.map
+</example>
+
+<p>You can then reference the resulting file in your
+<code>RewriteMap</code> directive:</p>
+
+<example>
+RewriteMap mapname dbm:/etc/apache/mapfile.map
+</example>
+
+<note>
+<p>Note that with some dbm types, more than one file is generated, with
+a common base name. For example, you may have two files named
+<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
+normal, and you need only use the base name <code>mapfile.map</code> in
+your <code>RewriteMap</code> directive.</p>
+</note>
+
+<note><title>Cached lookups</title>
+<p>
+The looked-up keys are cached by httpd until the <code>mtime</code>
+(modified time) of the mapfile changes, or the httpd server is
+restarted. This ensures better performance on maps that are called
+by many requests.
+</p>
+</note>
+
+ </section>
+
+ <section id="int">
+ <title>int: Internal Function</title>
+
+ <p>When a MapType of <code>int</code> is used, the MapSource is one
+ of the available internal RewriteMap functions. Module authors can provide
+ additional internal functions by registering them with the
+ <code>ap_register_rewrite_mapfunc</code> API.
+ The functions that are provided by default are:
+ </p>
+
+ <ul>
+ <li><strong>toupper</strong>:<br/>
+ Converts the key to all upper case.</li>
+ <li><strong>tolower</strong>:<br/>
+ Converts the key to all lower case.</li>
+ <li><strong>escape</strong>:<br/>
+ Translates special characters in the key to
+ hex-encodings.</li>
+ <li><strong>unescape</strong>:<br/>
+ Translates hex-encodings in the key back to
+ special characters.</li>
+ </ul>
+
+ <p>
+ To use one of these functions, create a <code>RewriteMap</code> referencing
+ the int function, and then use that in your <code>RewriteRule</code>:
+ </p>
+
+ <example><title>Redirect a URI to an all-lowercase version of itself</title>
+ RewriteMap lc int:tolower<br />
+ RewriteRule (.*[A-Z]+.*) ${lc:$1} [R]
+ </example>
+
+ <note>
+ <p>Please note that the example offered here is for
+ illustration purposes only, and is not a recommendation. If you want
+ to make URLs case-insensitive, consider using
+ <module>mod_speling</module> instead.
+ </p>
+ </note>
+
+ </section>
+
+ <section id="prg"><title>prg: External Rewriting Program</title>
+
+ <p>When a MapType of <code>prg</code> is used, the MapSource is a
+ filesystem path to an executable program which will providing the
+ mapping behavior. This can be a compiled binary file, or a program
+ in an interpreted language such as Perl or Python.</p>
+
+ <p>This program is started once, when the Apache HTTP Server is
+ started, and then communicates with the rewriting engine via
+ <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
+ function lookup, it expects one argument via <code>STDIN</code>, and
+ should return one new-line terminated response string on
+ <code>STDOUT</code>. If there is no corresponding lookup value, the
+ map program should return the four-character string
+ "<code>NULL</code>" to indicate this.</p>
+
+ <p>External rewriting programs are not started if they're defined in
+ a context that does not have <directive
+ module="mod_rewrite">RewriteEngine</directive> set to
+ <code>on</code>.</p>
+
+ <p>This feature utilizes the <code>rewrite-map</code> mutex,
+ which is required for reliable communication with the program.
+ The mutex mechanism and lock file can be configured with the
+ <directive module="core">Mutex</directive> directive.</p>
+
+ <p>A simple example is shown here which will replace all dashes with
+ underscores in a request URI.</p>
+
+ <example><title>Rewrite configuration</title>
+ RewriteMap d2u prg:/www/bin/dash2under.pl<br />
+ RewriteRule - ${d2u:%{REQUEST_URI}}
+ </example>
+
+ <example><title>dash2under.pl</title>
+ #!/usr/bin/perl<br />
+ $| = 1; # Turn off I/O buffering<br />
+ while (<STDIN>) {<br />
+ <indent>
+ s/-/_/g; # Replace dashes with underscores<br />
+ print $_;<br />
+ </indent>
+ }<br />
+ </example>
+
+<note><title>Caution!</title>
+<ul>
+<li>Keep your rewrite map program as simple as possible. If the program
+hangs, it will cause httpd to wait indefinitely for a response from the
+map, which will, in turn, cause httpd to stop responding to
+requests.</li>
+<li>Be sure to turn off buffering in your program. In Perl this is done
+by the second line in the example script: <code>$| = 1;</code> This will
+of course vary in other languages. Buffered I/O will cause httpd to wait
+for the output, and so it will hang.</li>
+<li>Remember that there is only one copy of the program, started at
+server startup. All requests will need to go through this one bottleneck.
+This can cause significant slowdowns if many requests must go through
+this process, or if the script itself is very slow.</li>
+</ul>
+</note>
+
+</section>
+
+
+ <section id="dbd">
+ <title>dbd or fastdbd: SQL Query</title>
+
+ <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
+ used, the MapSource is a SQL SELECT statement that takes a single
+ argument and returns a single value.</p>
+
+ <p><module>mod_dbd</module> will need to be configured to point at
+ the right database for this statement to be executed.</p>
+
+ <p>There are two forms of this MapType.
+ Using a MapType of <code>dbd</code> causes the query to be
+ executed with each map request, while using <code>fastdbd</code>
+ caches the database lookups internally. So, while
+ <code>fastdbd</code> is more efficient, and therefore faster, it
+ won't pick up on changes to the database until the server is
+ restarted.</p>
+
+ <p>If a query returns more than one row, a random row from
+the result set is used.</p>
+
+ <example><title>Example</title>
+RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
+ </example>
+
+ </section>
+ <section id="summary">
+ <title>Summary</title>
+
+ <p>The <directive>RewriteMap</directive> directive can occur more than
+ once. For each mapping-function use one
+ <directive>RewriteMap</directive> directive to declare its rewriting
+ mapfile.</p>
+
+ <p>While you cannot <strong>declare</strong> a map in
+ per-directory context (<code>.htaccess</code> files or
+ <Directory> blocks) it is possible to
+ <strong>use</strong> this map in per-directory context. </p>
+
+ </section>
+</manualpage>
Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml.meta
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml.meta?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml.meta (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml.meta Fri Mar 18 13:37:20 2011
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- GENERATED FROM XML: DO NOT EDIT -->
+
+<metafile reference="rewritemap.xml">
+ <basename>rewritemap</basename>
+ <path>/rewrite/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html Fri Mar 18 13:37:20 2011
@@ -0,0 +1,9 @@
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: tech.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1
+
+URI: tech.html.fr
+Content-Language: fr
+Content-type: text/html; charset=ISO-8859-1
Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.en?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.en (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.en Fri Mar 18 13:37:20 2011
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ This file is generated from xml source: DO NOT EDIT
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ -->
+<title>Apache mod_rewrite Technical Details - Apache HTTP Server</title>
+<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
+<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
+<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
+<link href="../images/favicon.ico" rel="shortcut icon" /></head>
+<body id="manual-page"><div id="page-header">
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
+<p class="apache">Apache HTTP Server Version 2.2</p>
+<img alt="" src="../images/feather.gif" /></div>
+<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
+<div id="path">
+<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.2</a> > <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Technical Details</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/rewrite/tech.html" title="English"> en </a> |
+<a href="../fr/rewrite/tech.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
+</div>
+
+<p>This document discusses some of the technical details of mod_rewrite
+and URL matching.</p>
+</div>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#Internal">Internal Processing</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#InternalAPI">API Phases</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#InternalRuleset">Ruleset Processing</a></li>
+</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="rewritemap.html">Using RewriteMap</a></li><li><a href="advanced.html">Advanced techniques and tricks</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="Internal" id="Internal">Internal Processing</a></h2>
+
+ <p>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.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="InternalAPI" id="InternalAPI">API Phases</a></h2>
+
+ <p>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.</p>
+
+ <p>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:</p>
+
+ <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, <em>i.e.</em>, 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.
+
+ <p>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.</p>
+ </li>
+ </ol>
+
+ <p>Don't forget these two points!</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="InternalRuleset" id="InternalRuleset">Ruleset Processing</a></h2>
+
+ <p>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. </p>
+
+ <p>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 class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></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.</p>
+<p class="figure">
+ <img src="../images/rewrite_rule_flow.png" alt="Flow of RewriteRule and RewriteCond matching" /><br />
+ <dfn>Figure 1:</dfn>The control flow through the rewriting ruleset
+</p>
+ <p>As you can see, first the URL is matched against the
+ <em>Pattern</em> of each rule. When it fails mod_rewrite
+ immediately stops processing this rule and continues with the
+ next rule. If the <em>Pattern</em> 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 <em>Substitution</em> 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 <em>TestString</em> by expanding variables,
+ back-references, map lookups, <em>etc.</em> and then we try
+ to match <em>CondPattern</em> 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
+ <em>Substitution</em>.</p>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/tech.html" title="English"> en </a> |
+<a href="../fr/rewrite/tech.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
+</div><div id="footer">
+<p class="apache">Copyright 2011 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
+</body></html>
\ No newline at end of file
Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.fr
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.fr?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.fr (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.fr Fri Mar 18 13:37:20 2011
@@ -0,0 +1,178 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="fr" xml:lang="fr"><head><!--
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ This file is generated from xml source: DO NOT EDIT
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ -->
+<title>Détails techniques sur le module Apache mod_rewrite - Serveur Apache HTTP</title>
+<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
+<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
+<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
+<link href="../images/favicon.ico" rel="shortcut icon" /></head>
+<body id="manual-page"><div id="page-header">
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossaire</a> | <a href="../sitemap.html">Plan du site</a></p>
+<p class="apache">Serveur Apache HTTP Version 2.2</p>
+<img alt="" src="../images/feather.gif" /></div>
+<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
+<div id="path">
+<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">Serveur HTTP</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.2</a> > <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Détails techniques sur le module Apache mod_rewrite</h1>
+<div class="toplang">
+<p><span>Langues Disponibles: </span><a href="../en/rewrite/tech.html" hreflang="en" rel="alternate" title="English"> en </a> |
+<a href="../fr/rewrite/tech.html" title="Français"> fr </a></p>
+</div>
+
+<p>Ce document passe en revue certains détails techniques à propos du
+module mod_rewrite et de la mise en correspondance des URLs</p>
+</div>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#Internal">Fonctionnement interne</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#InternalAPI">Phases de l'API</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#InternalRuleset">Traitement du jeu de règles</a></li>
+</ul><h3>Voir aussi</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Documentation du module mod_rewrite</a></li><li><a href="intro.html">Introduction à mod_rewrite</a></li><li><a href="remapping.html">Redirection et remise en
+correspondance</a></li><li><a href="access.html">Contrôle d'accès</a></li><li><a href="vhosts.html">Serveurs virtuels</a></li><li><a href="proxy.html">Mise en cache</a></li><li><a href="rewritemap.html">Utilisation de RewriteMap</a></li><li><a href="advanced.html">Techniques avancées et astuces</a></li><li><a href="avoid.html">Quand ne pas utiliser mod_rewrite</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="Internal" id="Internal">Fonctionnement interne</a></h2>
+
+ <p>Le fonctionnement interne de ce module est très complexe, mais
+ il est nécessaire de l'expliquer, même à l'utilisateur "standard",
+ afin d'éviter les erreurs courantes et de pouvoir exploiter toutes
+ ses fonctionnalités.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="InternalAPI" id="InternalAPI">Phases de l'API</a></h2>
+
+ <p>Il faut tout d'abord bien comprendre que le traitement d'une
+ requête HTTP par Apache s'effectue en plusieurs phases. L'API
+ d'Apache fournit un point d'accroche (hook) pour chacune de ces
+ phases. Mod_rewrite utilise deux de ces hooks : le hook de
+ conversion des URLs en noms de fichiers qui est utilisé quand la
+ requête HTTP a été lue mais avant le démarrage de tout processus
+ d'autorisation, et le hook "Fixup" qui est déclenché après les
+ phases d'autorisation et après la lecture des fichiers de
+ configuration niveau répertoire (<code>.htaccess</code>), mais
+ avant que le gestionnaire de contenu soit activé.</p>
+
+ <p>Donc, lorsqu'une requête arrive et quand Apache a déterminé le
+ serveur correspondant (ou le serveur virtuel), le moteur de
+ réécriture commence le traitement de toutes les directives de
+ mod_rewrite de la configuration du serveur principal dans la phase
+ de conversion URL vers nom de fichier. Une fois ces étapes
+ franchies, lorsque les repertoires de données finaux ont été
+ trouvés, les directives de configuration de mod_rewrite au niveau
+ répertoire sont éxécutées dans la phase Fixup. Dans les deux cas,
+ mod_rewrite réécrit les URLs soit en nouvelles URLs, soit en noms
+ de fichiers, bien que la distinction entre les deux ne soit pas
+ évidente. Cette utilisation de l'API n'était pas sensée s'opérer
+ de cette manière lorsque l'API fut conçue, mais depuis Apache 1.x,
+ c'est le seul mode opératoire possible pour mod_rewrite. Afin de
+ rendre les choses plus claires, souvenez-vous de ces deux points :</p>
+
+ <ol>
+ <li>Bien que mod_rewrite réécrive les URLs en URLs, les URLs en
+ noms de fichiers et même des noms de fichiers en d'autres noms
+ de fichiers, l'API ne propose actuellement qu'un hook URL vers
+ nom de fichier. Les deux hooks manquants seront ajoutés dans
+ Apache à partir de la version 2.0 afin de rendre le processus
+ plus clair. Mais ce point ne présente pas d'inconvénient pour
+ l'utilisateur, il s'agit simplement d'un fait que vous devez
+ garder à l'esprit : Apache en fait plus avec le hook URL vers
+ nom de fichier que l'API n'a la prétention d'en faire.</li>
+
+ <li>
+ Paradoxalement, mod_rewrite permet la manipulation d'URLs dans
+ un contexte de répertoire, <em>c'est à dire</em> dans les
+ fichiers <code>.htaccess</code>, bien que ces derniers
+ soient traités bien longtemps après que les URLs n'aient été
+ traduites en noms de fichiers. Les choses doivent se dérouler
+ ainsi car les fichiers <code>.htaccess</code> résident dans le
+ système de fichiers, et le traitement a déjà atteint
+ cette étape. Autrement dit, en accord avec les phases de
+ l'API, à ce point du traitement, il est trop tard pour
+ effectuer des manipulations d'URLs. Pour résoudre ce problème
+ d'antériorité, mod_rewrite utilise une astuce : pour effectuer
+ une manipulation URL/nom de fichier dans un contexte de
+ répertoire, mod_rewrite réécrit tout d'abord le nom de fichier
+ en son URL d'origine (ce qui est normalement impossible, mais
+ voir ci-dessous l'astuce utilisée par la directive
+ <code>RewriteBase</code> pour y parvenir), puis
+ initialise une nouvelle sous-requête interne avec la nouvelle
+ URL ; ce qui a pour effet de redémarrer le processus des
+ phases de l'API.
+
+ <p>Encore une fois, mod_rewrite fait tout ce qui est en son
+ pouvoir pour rendre la complexité de cette étape complètement
+ transparente à l'utilisateur, mais vous devez garder ceci à
+ l'esprit : alors que les manipulations d'URLs dans le contexte
+ du serveur sont vraiment rapides et efficaces, les réécritures
+ dans un contexte de répertoire sont lentes et inefficaces à
+ cause du problème d'antériorité précité. Cependant, c'est la
+ seule manière dont mod_rewrite peut proposer des manipulations
+ d'URLs (limitées à une branche du système de fichiers) à
+ l'utilisateur standard.</p>
+ </li>
+ </ol>
+
+ <p>Ne perdez pas de vue ces deux points!</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="InternalRuleset" id="InternalRuleset">Traitement du jeu de règles</a></h2>
+
+ <p>Maintenant, quand mod_rewrite se lance dans ces deux phases de
+ l'API, il lit le jeu de règles configurées depuis la structure
+ contenant sa configuration (qui a été elle-même créée soit au
+ démarrage d'Apache pour le contexte du serveur, soit lors du
+ parcours des répertoires par le noyau d'Apache pour le contexte de
+ répertoire). Puis le moteur de réécriture est démarré avec le jeu
+ de règles contenu (une ou plusieurs règles associées à leurs
+ conditions). En lui-même, le mode opératoire du moteur de
+ réécriture d'URLs est exactement le même dans les deux contextes
+ de configuration. Seul le traitement du résultat final diffère.</p>
+
+ <p>L'ordre dans lequel les règles sont définies est important car
+ le moteur de réécriture les traite selon une chronologie
+ particulière (et pas très évidente). Le principe est le suivant :
+ le moteur de réécriture traite les règles (les directives <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>) les unes
+ à la suite des autres, et lorsqu'une règle s'applique, il parcourt
+ les éventuelles conditions (directives
+ <code>RewriteCond</code>directives) associées.
+ Pour des raisons historiques, les
+ conditions précèdent les règles, si bien que le déroulement du
+ contrôle est un peu compliqué. Voir la figure 1 pour plus de
+ détails.</p>
+<p class="figure">
+ <img src="../images/rewrite_rule_flow.png" alt="Flux des comparaisons des directives RewriteRule et RewriteCond" /><br />
+ <dfn>Figure 1:</dfn>Déroulement du contrôle à travers le jeu de
+ règles de réécriture
+</p>
+ <p>Comme vous pouvez le voir, l'URL est tout d'abord comparée au
+ <em>Modèle</em> de chaque règle. Lorsqu'une règle ne s'applique
+ pas, mod_rewrite stoppe immédiatement le traitement de cette règle
+ et passe à la règle suivante. Si l'URL correspond au
+ <em>Modèle</em>, mod_rewrite recherche la présence de conditions
+ correspondantes. S'il n'y en a pas, mod_rewrite remplace
+ simplement l'URL par une chaîne élaborée à partir de la chaîne de
+ <em>Substitution</em>, puis passe à la règle suivante. Si des
+ conditions sont présentes, mod_rewrite lance un bouclage
+ secondaire afin de les traiter selon l'ordre dans lequel elles
+ sont définies. La logique de traitement des conditions est
+ différente : on ne compare pas l'URL à un modèle. Une chaîne de
+ test <em>TestString</em> est tout d'abord élaborée en développant
+ des variables, des références arrières, des recherches dans des
+ tables de correspondances, etc..., puis cette chaîne de test est
+ comparée au modèle de condition <em>CondPattern</em>. Si le modèle
+ ne correspond pas, les autres conditions du jeu ne sont pas
+ examinées et la règle correspondante ne s'applique pas. Si le
+ modèle correspond, la condition suivante est examinée et ainsi de
+ suite jusqu'à la dernière condition. Si toutes les conditions sont
+ satisfaites, le traitement de la règle en cours se poursuit avec
+ le remplacement de l'URL par la chaîne de <em>Substitution</em>.</p>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Langues Disponibles: </span><a href="../en/rewrite/tech.html" hreflang="en" rel="alternate" title="English"> en </a> |
+<a href="../fr/rewrite/tech.html" title="Français"> fr </a></p>
+</div><div id="footer">
+<p class="apache">Copyright 2011 The Apache Software Foundation.<br />Autorisé sous <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossaire</a> | <a href="../sitemap.html">Plan du site</a></p></div>
+</body></html>
\ No newline at end of file
Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml Fri Mar 18 13:37:20 2011
@@ -0,0 +1,172 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 945974 $ -->
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<manualpage metafile="tech.xml.meta">
+<parentdocument href="./">Rewrite</parentdocument>
+
+ <title>Apache mod_rewrite Technical Details</title>
+
+<summary>
+<p>This document discusses some of the technical details of mod_rewrite
+and URL matching.</p>
+</summary>
+<seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
+<seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
+<seealso><a href="remapping.html">Redirection and remapping</a></seealso>
+<seealso><a href="access.html">Controlling access</a></seealso>
+<seealso><a href="vhosts.html">Virtual hosts</a></seealso>
+<seealso><a href="proxy.html">Proxying</a></seealso>
+<seealso><a href="rewritemap.html">Using RewriteMap</a></seealso>
+<seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>
+<seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
+
+<section id="Internal"><title>Internal Processing</title>
+
+ <p>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.</p>
+</section>
+
+<section id="InternalAPI"><title>API Phases</title>
+
+ <p>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.</p>
+
+ <p>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:</p>
+
+ <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, <em>i.e.</em>, 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.
+
+ <p>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.</p>
+ </li>
+ </ol>
+
+ <p>Don't forget these two points!</p>
+</section>
+
+<section id="InternalRuleset"><title>Ruleset Processing</title>
+
+ <p>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. </p>
+
+ <p>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 (<directive
+ module="mod_rewrite">RewriteRule</directive> 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.</p>
+<p class="figure">
+ <img src="../images/rewrite_rule_flow.png"
+ alt="Flow of RewriteRule and RewriteCond matching" /><br />
+ <dfn>Figure 1:</dfn>The control flow through the rewriting ruleset
+</p>
+ <p>As you can see, first the URL is matched against the
+ <em>Pattern</em> of each rule. When it fails mod_rewrite
+ immediately stops processing this rule and continues with the
+ next rule. If the <em>Pattern</em> 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 <em>Substitution</em> 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 <em>TestString</em> by expanding variables,
+ back-references, map lookups, <em>etc.</em> and then we try
+ to match <em>CondPattern</em> 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
+ <em>Substitution</em>.</p>
+
+</section>
+
+
+</manualpage>
+
Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.fr
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.fr?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.fr (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.fr Fri Mar 18 13:37:20 2011
@@ -0,0 +1,187 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
+<!-- English Revision : 945974 -->
+<!-- French translation : Lucien GENTIS -->
+<!-- Reviewed by : Vincent Deffontaines -->
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<manualpage metafile="tech.xml.meta">
+<parentdocument href="./">Rewrite</parentdocument>
+
+ <title>Détails techniques sur le module Apache mod_rewrite</title>
+
+<summary>
+<p>Ce document passe en revue certains détails techniques à propos du
+module mod_rewrite et de la mise en correspondance des URLs</p>
+</summary>
+<seealso><a href="../mod/mod_rewrite.html">Documentation du module mod_rewrite</a></seealso>
+<seealso><a href="intro.html">Introduction à mod_rewrite</a></seealso>
+<seealso><a href="remapping.html">Redirection et remise en
+correspondance</a></seealso>
+<seealso><a href="access.html">Contrôle d'accès</a></seealso>
+<seealso><a href="vhosts.html">Serveurs virtuels</a></seealso>
+<seealso><a href="proxy.html">Mise en cache</a></seealso>
+<seealso><a href="rewritemap.html">Utilisation de RewriteMap</a></seealso>
+<seealso><a href="advanced.html">Techniques avancées et astuces</a></seealso>
+<seealso><a href="avoid.html">Quand ne pas utiliser mod_rewrite</a></seealso>
+
+<section id="Internal"><title>Fonctionnement interne</title>
+
+ <p>Le fonctionnement interne de ce module est très complexe, mais
+ il est nécessaire de l'expliquer, même à l'utilisateur "standard",
+ afin d'éviter les erreurs courantes et de pouvoir exploiter toutes
+ ses fonctionnalités.</p>
+</section>
+
+<section id="InternalAPI"><title>Phases de l'API</title>
+
+ <p>Il faut tout d'abord bien comprendre que le traitement d'une
+ requête HTTP par Apache s'effectue en plusieurs phases. L'API
+ d'Apache fournit un point d'accroche (hook) pour chacune de ces
+ phases. Mod_rewrite utilise deux de ces hooks : le hook de
+ conversion des URLs en noms de fichiers qui est utilisé quand la
+ requête HTTP a été lue mais avant le démarrage de tout processus
+ d'autorisation, et le hook "Fixup" qui est déclenché après les
+ phases d'autorisation et après la lecture des fichiers de
+ configuration niveau répertoire (<code>.htaccess</code>), mais
+ avant que le gestionnaire de contenu soit activé.</p>
+
+ <p>Donc, lorsqu'une requête arrive et quand Apache a déterminé le
+ serveur correspondant (ou le serveur virtuel), le moteur de
+ réécriture commence le traitement de toutes les directives de
+ mod_rewrite de la configuration du serveur principal dans la phase
+ de conversion URL vers nom de fichier. Une fois ces étapes
+ franchies, lorsque les repertoires de données finaux ont été
+ trouvés, les directives de configuration de mod_rewrite au niveau
+ répertoire sont éxécutées dans la phase Fixup. Dans les deux cas,
+ mod_rewrite réécrit les URLs soit en nouvelles URLs, soit en noms
+ de fichiers, bien que la distinction entre les deux ne soit pas
+ évidente. Cette utilisation de l'API n'était pas sensée s'opérer
+ de cette manière lorsque l'API fut conçue, mais depuis Apache 1.x,
+ c'est le seul mode opératoire possible pour mod_rewrite. Afin de
+ rendre les choses plus claires, souvenez-vous de ces deux points :</p>
+
+ <ol>
+ <li>Bien que mod_rewrite réécrive les URLs en URLs, les URLs en
+ noms de fichiers et même des noms de fichiers en d'autres noms
+ de fichiers, l'API ne propose actuellement qu'un hook URL vers
+ nom de fichier. Les deux hooks manquants seront ajoutés dans
+ Apache à partir de la version 2.0 afin de rendre le processus
+ plus clair. Mais ce point ne présente pas d'inconvénient pour
+ l'utilisateur, il s'agit simplement d'un fait que vous devez
+ garder à l'esprit : Apache en fait plus avec le hook URL vers
+ nom de fichier que l'API n'a la prétention d'en faire.</li>
+
+ <li>
+ Paradoxalement, mod_rewrite permet la manipulation d'URLs dans
+ un contexte de répertoire, <em>c'est à dire</em> dans les
+ fichiers <code>.htaccess</code>, bien que ces derniers
+ soient traités bien longtemps après que les URLs n'aient été
+ traduites en noms de fichiers. Les choses doivent se dérouler
+ ainsi car les fichiers <code>.htaccess</code> résident dans le
+ système de fichiers, et le traitement a déjà atteint
+ cette étape. Autrement dit, en accord avec les phases de
+ l'API, à ce point du traitement, il est trop tard pour
+ effectuer des manipulations d'URLs. Pour résoudre ce problème
+ d'antériorité, mod_rewrite utilise une astuce : pour effectuer
+ une manipulation URL/nom de fichier dans un contexte de
+ répertoire, mod_rewrite réécrit tout d'abord le nom de fichier
+ en son URL d'origine (ce qui est normalement impossible, mais
+ voir ci-dessous l'astuce utilisée par la directive
+ <code>RewriteBase</code> pour y parvenir), puis
+ initialise une nouvelle sous-requête interne avec la nouvelle
+ URL ; ce qui a pour effet de redémarrer le processus des
+ phases de l'API.
+
+ <p>Encore une fois, mod_rewrite fait tout ce qui est en son
+ pouvoir pour rendre la complexité de cette étape complètement
+ transparente à l'utilisateur, mais vous devez garder ceci à
+ l'esprit : alors que les manipulations d'URLs dans le contexte
+ du serveur sont vraiment rapides et efficaces, les réécritures
+ dans un contexte de répertoire sont lentes et inefficaces à
+ cause du problème d'antériorité précité. Cependant, c'est la
+ seule manière dont mod_rewrite peut proposer des manipulations
+ d'URLs (limitées à une branche du système de fichiers) à
+ l'utilisateur standard.</p>
+ </li>
+ </ol>
+
+ <p>Ne perdez pas de vue ces deux points!</p>
+</section>
+
+<section id="InternalRuleset"><title>Traitement du jeu de règles</title>
+
+ <p>Maintenant, quand mod_rewrite se lance dans ces deux phases de
+ l'API, il lit le jeu de règles configurées depuis la structure
+ contenant sa configuration (qui a été elle-même créée soit au
+ démarrage d'Apache pour le contexte du serveur, soit lors du
+ parcours des répertoires par le noyau d'Apache pour le contexte de
+ répertoire). Puis le moteur de réécriture est démarré avec le jeu
+ de règles contenu (une ou plusieurs règles associées à leurs
+ conditions). En lui-même, le mode opératoire du moteur de
+ réécriture d'URLs est exactement le même dans les deux contextes
+ de configuration. Seul le traitement du résultat final diffère.</p>
+
+ <p>L'ordre dans lequel les règles sont définies est important car
+ le moteur de réécriture les traite selon une chronologie
+ particulière (et pas très évidente). Le principe est le suivant :
+ le moteur de réécriture traite les règles (les directives <directive
+ module="mod_rewrite">RewriteRule</directive>) les unes
+ à la suite des autres, et lorsqu'une règle s'applique, il parcourt
+ les éventuelles conditions (directives
+ <code>RewriteCond</code>directives) associées.
+ Pour des raisons historiques, les
+ conditions précèdent les règles, si bien que le déroulement du
+ contrôle est un peu compliqué. Voir la figure 1 pour plus de
+ détails.</p>
+<p class="figure">
+ <img src="../images/rewrite_rule_flow.png"
+ alt="Flux des comparaisons des directives RewriteRule et RewriteCond" /><br />
+ <dfn>Figure 1:</dfn>Déroulement du contrôle à travers le jeu de
+ règles de réécriture
+</p>
+ <p>Comme vous pouvez le voir, l'URL est tout d'abord comparée au
+ <em>Modèle</em> de chaque règle. Lorsqu'une règle ne s'applique
+ pas, mod_rewrite stoppe immédiatement le traitement de cette règle
+ et passe à la règle suivante. Si l'URL correspond au
+ <em>Modèle</em>, mod_rewrite recherche la présence de conditions
+ correspondantes. S'il n'y en a pas, mod_rewrite remplace
+ simplement l'URL par une chaîne élaborée à partir de la chaîne de
+ <em>Substitution</em>, puis passe à la règle suivante. Si des
+ conditions sont présentes, mod_rewrite lance un bouclage
+ secondaire afin de les traiter selon l'ordre dans lequel elles
+ sont définies. La logique de traitement des conditions est
+ différente : on ne compare pas l'URL à un modèle. Une chaîne de
+ test <em>TestString</em> est tout d'abord élaborée en développant
+ des variables, des références arrières, des recherches dans des
+ tables de correspondances, etc..., puis cette chaîne de test est
+ comparée au modèle de condition <em>CondPattern</em>. Si le modèle
+ ne correspond pas, les autres conditions du jeu ne sont pas
+ examinées et la règle correspondante ne s'applique pas. Si le
+ modèle correspond, la condition suivante est examinée et ainsi de
+ suite jusqu'à la dernière condition. Si toutes les conditions sont
+ satisfaites, le traitement de la règle en cours se poursuit avec
+ le remplacement de l'URL par la chaîne de <em>Substitution</em>.</p>
+
+</section>
+
+
+</manualpage>
+
Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.meta
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.meta?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.meta (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.meta Fri Mar 18 13:37:20 2011
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- GENERATED FROM XML: DO NOT EDIT -->
+
+<metafile reference="tech.xml">
+ <basename>tech</basename>
+ <path>/rewrite/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant>fr</variant>
+ </variants>
+</metafile>
Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/vhosts.html
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/vhosts.html?rev=1082915&view=auto
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/rewrite/vhosts.html (added)
+++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/vhosts.html Fri Mar 18 13:37:20 2011
@@ -0,0 +1,5 @@
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: vhosts.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1