# GENERATED FROM XML -- DO NOT EDIT
-URI: rewrite_tech.html.en
+URI: access.html.en
Content-Language: en
Content-type: text/html; charset=ISO-8859-1
--- /dev/null
+<?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 mod_rewrite to control access - 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 mod_rewrite to control access</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/rewrite/access.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
+how you can use <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to control access to
+various resources, and other related techniques.
+This includes many examples of common uses of mod_rewrite,
+including detailed descriptions of how each works.</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="#blocked-inline-images">Forbidding Image "Hotlinking"</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#blocking-of-robots">Blocking of Robots</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#host-deny">Denying Hosts in a Blacklist</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#referer-deflector">Referer-based Deflector</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="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="blocked-inline-images" id="blocked-inline-images">Forbidding Image "Hotlinking"</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>The following technique forbids the practice of other sites
+ including your images inline in their pages. This practice is
+ often referred to as "hotlinking", and results in
+ your bandwidth being used to serve content for someone else's
+ site.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>This technique relies on the value of the
+ <code>HTTP_REFERER</code> variable, which is optional. As
+ such, it's possible for some people to circumvent this
+ limitation. However, most users will experience the failed
+ request, which should, over time, result in the image being
+ removed from that other site.</p>
+ <p>There are several ways that you can handle this
+ situation.</p>
+
+ <p>In this first example, we simply deny the request, if it didn't
+ initiate from a page on our site. For the purpose of this example,
+ we assume that our site is <code>www.example.com</code>.</p>
+
+<div class="example"><p><code>
+RewriteCond %{HTTP_REFERER} <strong>!^$</strong><br />
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]<br />
+RewriteRule <strong>\.(gif|jpg|png)$</strong> - [F,NC]
+</code></p></div>
+
+ <p>In this second example, instead of failing the request, we display
+ an alternate image instead.</p>
+
+<div class="example"><p><code>
+RewriteCond %{HTTP_REFERER} <strong>!^$</strong><br />
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]<br />
+RewriteRule <strong>\.(gif|jpg|png)$</strong> /images/go-away.png [R,NC]
+</code></p></div>
+
+ <p>In the third example, we redirect the request to an image on some
+ other site.</p>
+
+<div class="example"><p><code>
+RewriteCond %{HTTP_REFERER} <strong>!^$</strong><br />
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]<br />
+RewriteRule <strong>\.(gif|jpg|png)$</strong> http://other.example.com/image.gif [R,NC]
+</code></p></div>
+
+ <p>Of these techniques, the last two tend to be the most effective
+ in getting people to stop hotlinking your images, because they will
+ simply not see the image that they expected to see.</p>
+
+ </dd>
+
+ <dt>Discussion:</dt>
+
+ <dd>
+ <p>If all you wish to do is deny access to the resource, rather
+ than redirecting that request elsewhere, this can be
+ accomplished without the use of mod_rewrite:</p>
+
+ <div class="example"><p><code>
+ SetEnvIf Referer example\.com localreferer<br />
+ <FilesMatch \.(jpg|png|gif)$><br />
+ Order deny,allow<br />
+ Deny from all<br />
+ Allow from env=localreferer<br />
+ </FilesMatch>
+ </code></p></div>
+ </dd>
+ </dl>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="blocking-of-robots" id="blocking-of-robots">Blocking of Robots</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>
+ In this recipe, we discuss how to block persistent requests from
+ a particular robot, or user agent.</p>
+
+ <p>The standard for robot exclusion defines a file,
+ <code>/robots.txt</code> that specifies those portions of your
+ website where you which to exclude robots. However, some robots
+ do not honor these files.
+ </p>
+
+ <p>Note that there are methods of accomplishing this which do
+ not use mod_rewrite. Note also that any technique that relies on
+ the clients <code>USER_AGENT</code> string can be circumvented
+ very easily, since that string can be changed.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We use a ruleset that specifies the directory to be
+ protected, and the client <code>USER_AGENT</code> that
+ identifies the malicious or persistent robot.</p>
+
+ <p>In this example, we are blocking a robot called
+ <code>NameOfBadRobot</code> from a location
+ <code>/secret/files</code>. You may also specify an IP address
+ range, if you are trying to block that user agent only from the
+ particular source.</p>
+
+<div class="example"><p><code>
+RewriteCond %{HTTP_USER_AGENT} ^<strong>NameOfBadRobot</strong><br />
+RewriteCond %{REMOTE_ADDR} =<strong>123\.45\.67\.[8-9]</strong><br />
+RewriteRule ^<strong>/secret/files/</strong> - [<strong>F</strong>]
+</code></p></div>
+ </dd>
+
+ <dt>Discussion:</dt>
+
+ <dd>
+ <p>
+ Rather than using mod_rewrite for this, you can accomplish the
+ same end using alternate means, as illustrated here:
+ </p>
+ <div class="example"><p><code>
+ SetEnvIfNoCase User-Agent ^NameOfBadRobot goaway<br />
+ <Location /secret/files><br />
+ Order allow,deny<br />
+ Allow from all<br />
+ Deny from env=goaway<br />
+ </Location>
+ </code></p></div>
+ <p>
+ As noted above, this technique is trivial to circumvent, by simply
+ modifying the <code>USER_AGENT</code> request header. If you
+ are experiencing a sustained attack, you should consider blocking
+ it at a higher level, such as at your firewall.
+ </p>
+
+ </dd>
+
+ </dl>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="host-deny" id="host-deny">Denying Hosts in a Blacklist</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We wish to maintain a blacklist of hosts, rather like
+ <code>hosts.deny</code>, and have those hosts blocked from
+ accessing our server.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+<div class="example"><p><code>
+RewriteEngine on<br />
+RewriteMap hosts-deny txt:/path/to/hosts.deny<br />
+RewriteCond ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND [OR]<br />
+RewriteCond ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND<br />
+RewriteRule ^ - [F]
+</code></p></div>
+
+<div class="example"><p><code>
+##<br />
+## hosts.deny<br />
+##<br />
+## ATTENTION! This is a map, not a list, even when we treat it as such.<br />
+## mod_rewrite parses it for key/value pairs, so at least a<br />
+## dummy value "-" must be present for each entry.<br />
+##<br />
+<br />
+193.102.180.41 -<br />
+bsdti1.sdm.de -<br />
+192.76.162.40 -<br />
+</code></p></div>
+ </dd>
+
+ <dt>Discussion:</dt>
+ <dd>
+ <p>
+ The second RewriteCond assumes that you have HostNameLookups turned
+ on, so that client IP addresses will be resolved. If that's not the
+ case, you should drop the second RewriteCond, and drop the
+ <code>[OR]</code> flag from the first RewriteCond.
+ </p>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="referer-deflector" id="referer-deflector">Referer-based Deflector</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>Redirect requests based on the Referer from which the request
+ came, with different targets per Referer.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>The following ruleset uses a map file to associate each Referer
+ with a redirection target.</p>
+
+<div class="example"><p><code>
+RewriteMap deflector txt:/path/to/deflector.map<br />
+<br />
+RewriteCond %{HTTP_REFERER} !=""<br />
+RewriteCond ${deflector:%{HTTP_REFERER}} =-<br />
+RewriteRule ^ %{HTTP_REFERER} [R,L]<br />
+<br />
+RewriteCond %{HTTP_REFERER} !=""<br />
+RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND<br />
+RewriteRule ^.* ${deflector:%{HTTP_REFERER}} [R,L]
+</code></p></div>
+
+ <p>The map file lists redirection targets for each referer, or, if
+ we just wish to redirect back to where they came from, a "-" is
+ placed in the map:</p>
+
+<div class="example"><p><code>
+##<br />
+## deflector.map<br />
+##<br />
+<br />
+http://badguys.example.com/bad/index.html -<br />
+http://badguys.example.com/bad/index2.html -<br />
+http://badguys.example.com/bad/index3.html http://somewhere.example.com/
+</code></p></div>
+
+ </dd>
+ </dl>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/access.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
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 1059165 $ -->
+
+<!--
+ 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="access.xml.meta">
+ <parentdocument href="./">Rewrite</parentdocument>
+
+<title>Using mod_rewrite to control access</title>
+
+<summary>
+
+<p>This document supplements the <module>mod_rewrite</module>
+<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
+how you can use <module>mod_rewrite</module> to control access to
+various resources, and other related techniques.
+This includes many examples of common uses of mod_rewrite,
+including detailed descriptions of how each works.</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="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="blocked-inline-images">
+
+ <title>Forbidding Image "Hotlinking"</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>The following technique forbids the practice of other sites
+ including your images inline in their pages. This practice is
+ often referred to as "hotlinking", and results in
+ your bandwidth being used to serve content for someone else's
+ site.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>This technique relies on the value of the
+ <code>HTTP_REFERER</code> variable, which is optional. As
+ such, it's possible for some people to circumvent this
+ limitation. However, most users will experience the failed
+ request, which should, over time, result in the image being
+ removed from that other site.</p>
+ <p>There are several ways that you can handle this
+ situation.</p>
+
+ <p>In this first example, we simply deny the request, if it didn't
+ initiate from a page on our site. For the purpose of this example,
+ we assume that our site is <code>www.example.com</code>.</p>
+
+<example>
+RewriteCond %{HTTP_REFERER} <strong>!^$</strong><br />
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]<br />
+RewriteRule <strong>\.(gif|jpg|png)$</strong> - [F,NC]
+</example>
+
+ <p>In this second example, instead of failing the request, we display
+ an alternate image instead.</p>
+
+<example>
+RewriteCond %{HTTP_REFERER} <strong>!^$</strong><br />
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]<br />
+RewriteRule <strong>\.(gif|jpg|png)$</strong> /images/go-away.png [R,NC]
+</example>
+
+ <p>In the third example, we redirect the request to an image on some
+ other site.</p>
+
+<example>
+RewriteCond %{HTTP_REFERER} <strong>!^$</strong><br />
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]<br />
+RewriteRule <strong>\.(gif|jpg|png)$</strong> http://other.example.com/image.gif [R,NC]
+</example>
+
+ <p>Of these techniques, the last two tend to be the most effective
+ in getting people to stop hotlinking your images, because they will
+ simply not see the image that they expected to see.</p>
+
+ </dd>
+
+ <dt>Discussion:</dt>
+
+ <dd>
+ <p>If all you wish to do is deny access to the resource, rather
+ than redirecting that request elsewhere, this can be
+ accomplished without the use of mod_rewrite:</p>
+
+ <example>
+ SetEnvIf Referer example\.com localreferer<br />
+ <FilesMatch \.(jpg|png|gif)$><br />
+ Order deny,allow<br />
+ Deny from all<br />
+ Allow from env=localreferer<br />
+ </FilesMatch>
+ </example>
+ </dd>
+ </dl>
+
+ </section>
+
+ <section id="blocking-of-robots">
+
+ <title>Blocking of Robots</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>
+ In this recipe, we discuss how to block persistent requests from
+ a particular robot, or user agent.</p>
+
+ <p>The standard for robot exclusion defines a file,
+ <code>/robots.txt</code> that specifies those portions of your
+ website where you which to exclude robots. However, some robots
+ do not honor these files.
+ </p>
+
+ <p>Note that there are methods of accomplishing this which do
+ not use mod_rewrite. Note also that any technique that relies on
+ the clients <code>USER_AGENT</code> string can be circumvented
+ very easily, since that string can be changed.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We use a ruleset that specifies the directory to be
+ protected, and the client <code>USER_AGENT</code> that
+ identifies the malicious or persistent robot.</p>
+
+ <p>In this example, we are blocking a robot called
+ <code>NameOfBadRobot</code> from a location
+ <code>/secret/files</code>. You may also specify an IP address
+ range, if you are trying to block that user agent only from the
+ particular source.</p>
+
+<example>
+RewriteCond %{HTTP_USER_AGENT} ^<strong>NameOfBadRobot</strong><br />
+RewriteCond %{REMOTE_ADDR} =<strong>123\.45\.67\.[8-9]</strong><br />
+RewriteRule ^<strong>/secret/files/</strong> - [<strong>F</strong>]
+</example>
+ </dd>
+
+ <dt>Discussion:</dt>
+
+ <dd>
+ <p>
+ Rather than using mod_rewrite for this, you can accomplish the
+ same end using alternate means, as illustrated here:
+ </p>
+ <example>
+ SetEnvIfNoCase User-Agent ^NameOfBadRobot goaway<br />
+ <Location /secret/files><br />
+ Order allow,deny<br />
+ Allow from all<br />
+ Deny from env=goaway<br />
+ </Location>
+ </example>
+ <p>
+ As noted above, this technique is trivial to circumvent, by simply
+ modifying the <code>USER_AGENT</code> request header. If you
+ are experiencing a sustained attack, you should consider blocking
+ it at a higher level, such as at your firewall.
+ </p>
+
+ </dd>
+
+ </dl>
+
+ </section>
+
+<section id="host-deny">
+
+ <title>Denying Hosts in a Blacklist</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We wish to maintain a blacklist of hosts, rather like
+ <code>hosts.deny</code>, and have those hosts blocked from
+ accessing our server.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+<example>
+RewriteEngine on<br />
+RewriteMap hosts-deny txt:/path/to/hosts.deny<br />
+RewriteCond ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND [OR]<br />
+RewriteCond ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND<br />
+RewriteRule ^ - [F]
+</example>
+
+<example>
+##<br />
+## hosts.deny<br />
+##<br />
+## ATTENTION! This is a map, not a list, even when we treat it as such.<br />
+## mod_rewrite parses it for key/value pairs, so at least a<br />
+## dummy value "-" must be present for each entry.<br />
+##<br />
+<br />
+193.102.180.41 -<br />
+bsdti1.sdm.de -<br />
+192.76.162.40 -<br />
+</example>
+ </dd>
+
+ <dt>Discussion:</dt>
+ <dd>
+ <p>
+ The second RewriteCond assumes that you have HostNameLookups turned
+ on, so that client IP addresses will be resolved. If that's not the
+ case, you should drop the second RewriteCond, and drop the
+ <code>[OR]</code> flag from the first RewriteCond.
+ </p>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="referer-deflector">
+
+ <title>Referer-based Deflector</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>Redirect requests based on the Referer from which the request
+ came, with different targets per Referer.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>The following ruleset uses a map file to associate each Referer
+ with a redirection target.</p>
+
+<example>
+RewriteMap deflector txt:/path/to/deflector.map<br />
+<br />
+RewriteCond %{HTTP_REFERER} !=""<br />
+RewriteCond ${deflector:%{HTTP_REFERER}} =-<br />
+RewriteRule ^ %{HTTP_REFERER} [R,L]<br />
+<br />
+RewriteCond %{HTTP_REFERER} !=""<br />
+RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND<br />
+RewriteRule ^.* ${deflector:%{HTTP_REFERER}} [R,L]
+</example>
+
+ <p>The map file lists redirection targets for each referer, or, if
+ we just wish to redirect back to where they came from, a "-" is
+ placed in the map:</p>
+
+<example>
+##<br />
+## deflector.map<br />
+##<br />
+<br />
+http://badguys.example.com/bad/index.html -<br />
+http://badguys.example.com/bad/index2.html -<br />
+http://badguys.example.com/bad/index3.html http://somewhere.example.com/
+</example>
+
+ </dd>
+ </dl>
+
+</section>
+
+</manualpage>
<?xml version="1.0" encoding="UTF-8" ?>
<!-- GENERATED FROM XML: DO NOT EDIT -->
-<metafile reference="rewrite_tech.xml">
- <basename>rewrite_tech</basename>
+<metafile reference="access.xml">
+ <basename>access</basename>
<path>/rewrite/</path>
<relpath>..</relpath>
# GENERATED FROM XML -- DO NOT EDIT
-URI: rewrite_flags.html.en
+URI: advanced.html.en
Content-Language: en
Content-type: text/html; charset=ISO-8859-1
--- /dev/null
+<?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>Advanced Techniques with mod_rewrite - 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>Advanced Techniques with mod_rewrite</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/rewrite/avoid.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 provides
+a few advanced techniques and tricks using mod_rewrite.</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="#sharding">URL-based sharding accross multiple backends</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#on-the-fly-content">On-the-fly Content-Regeneration</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#load-balancing">Load Balancing</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#autorefresh">Document With Autorefresh</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#structuredhomedirs">Structured Userdirs</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#redirectanchors">Redirecting Anchors</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#time-dependent">Time-Dependent Rewriting</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#setenvvars">Set Environment Variables Based On URL Parts</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="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="sharding" id="sharding">URL-based sharding accross multiple backends</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>A common technique for distributing the burden of
+ server load or storage space is called "sharding".
+ When using this method, a front-end server will use the
+ url to consistently "shard" users or objects to separate
+ backend servers.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>A mapping is maintained, from users to target servers, in
+ external map files. They look like:</p>
+
+<div class="example"><p><code>
+user1 physical_host_of_user1<br />
+user2 physical_host_of_user2<br />
+: :
+</code></p></div>
+
+ <p>We put this into a <code>map.users-to-hosts</code> file. The
+ aim is to map;</p>
+
+<div class="example"><p><code>
+/u/user1/anypath
+</code></p></div>
+
+ <p>to</p>
+
+<div class="example"><p><code>
+http://physical_host_of_user1/u/user/anypath
+</code></p></div>
+
+ <p>thus every URL path need not be valid on every backend physical
+ host. The following ruleset does this for us with the help of the map
+ files assuming that server0 is a default server which will be used if
+ a user has no entry in the map:</p>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+<br />
+RewriteMap users-to-hosts txt:/path/to/map.users-to-hosts<br />
+<br />
+RewriteRule ^/u/<strong>([^/]+)</strong>/?(.*) http://<strong>${users-to-hosts:$1|server0}</strong>/u/$1/$2
+</code></p></div>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="on-the-fly-content" id="on-the-fly-content">On-the-fly Content-Regeneration</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We wish to dynamically generate content, but store it
+ statically once it is generated. This rule will check for the
+ existence of the static file, and if it's not there, generate
+ it. The static files can be removed periodically, if desired (say,
+ via cron) and will be regenerated on demand.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ This is done via the following ruleset:
+
+<div class="example"><p><code>
+# This example is valid in per-directory context only<br />
+RewriteCond %{REQUEST_FILENAME} <strong>!-s</strong><br />
+RewriteRule ^page\.<strong>html</strong>$ page.<strong>cgi</strong> [T=application/x-httpd-cgi,L]
+</code></p></div>
+
+ <p>Here a request for <code>page.html</code> leads to an
+ internal run of a corresponding <code>page.cgi</code> if
+ <code>page.html</code> is missing or has filesize
+ null. The trick here is that <code>page.cgi</code> is a
+ CGI script which (additionally to its <code>STDOUT</code>)
+ writes its output to the file <code>page.html</code>.
+ Once it has completed, the server sends out
+ <code>page.html</code>. When the webmaster wants to force
+ a refresh of the contents, he just removes
+ <code>page.html</code> (typically from <code>cron</code>).</p>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="load-balancing" id="load-balancing">Load Balancing</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We wish to randomly distribute load across several servers
+ using mod_rewrite.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We'll use <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> and a list of servers
+ to accomplish this.</p>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+RewriteMap lb rnd:/path/to/serverlist.txt<br />
+<br />
+RewriteRule ^/(.*) http://${lb:servers}/$1 [P,L]
+</code></p></div>
+
+<p><code>serverlist.txt</code> will contain a list of the servers:</p>
+
+<div class="example"><p><code>
+## serverlist.txt<br />
+<br />
+servers one.example.com|two.example.com|three.example.com<br />
+</code></p></div>
+
+<p>If you want one particular server to get more of the load than the
+others, add it more times to the list.</p>
+
+ </dd>
+
+ <dt>Discussion</dt>
+ <dd>
+<p>Apache comes with a load-balancing module -
+<code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code> - which is far more flexible and
+featureful than anything you can cobble together using mod_rewrite.</p>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="autorefresh" id="autorefresh">Document With Autorefresh</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>Wouldn't it be nice, while creating a complex web page, if
+ the web browser would automatically refresh the page every
+ time we save a new version from within our editor?
+ Impossible?</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>No! We just combine the MIME multipart feature, the
+ web server NPH feature, and the URL manipulation power of
+ <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. First, we establish a new
+ URL feature: Adding just <code>:refresh</code> to any
+ URL causes the 'page' to be refreshed every time it is
+ updated on the filesystem.</p>
+
+<div class="example"><p><code>
+RewriteRule ^(/[uge]/[^/]+/?.*):refresh /internal/cgi/apache/nph-refresh?f=$1
+</code></p></div>
+
+ <p>Now when we reference the URL</p>
+
+<div class="example"><p><code>
+/u/foo/bar/page.html:refresh
+</code></p></div>
+
+ <p>this leads to the internal invocation of the URL</p>
+
+<div class="example"><p><code>
+/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html
+</code></p></div>
+
+ <p>The only missing part is the NPH-CGI script. Although
+ one would usually say "left as an exercise to the reader"
+ ;-) I will provide this, too.</p>
+
+<div class="example"><pre>
+#!/sw/bin/perl
+##
+## nph-refresh -- NPH/CGI script for auto refreshing pages
+## Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.
+##
+$| = 1;
+
+# split the QUERY_STRING variable
+@pairs = split(/&/, $ENV{'QUERY_STRING'});
+foreach $pair (@pairs) {
+($name, $value) = split(/=/, $pair);
+$name =~ tr/A-Z/a-z/;
+$name = 'QS_' . $name;
+$value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
+eval "\$$name = \"$value\"";
+}
+$QS_s = 1 if ($QS_s eq '');
+$QS_n = 3600 if ($QS_n eq '');
+if ($QS_f eq '') {
+print "HTTP/1.0 200 OK\n";
+print "Content-type: text/html\n\n";
+print "&lt;b&gt;ERROR&lt;/b&gt;: No file given\n";
+exit(0);
+}
+if (! -f $QS_f) {
+print "HTTP/1.0 200 OK\n";
+print "Content-type: text/html\n\n";
+print "&lt;b&gt;ERROR&lt;/b&gt;: File $QS_f not found\n";
+exit(0);
+}
+
+sub print_http_headers_multipart_begin {
+print "HTTP/1.0 200 OK\n";
+$bound = "ThisRandomString12345";
+print "Content-type: multipart/x-mixed-replace;boundary=$bound\n";
+&print_http_headers_multipart_next;
+}
+
+sub print_http_headers_multipart_next {
+print "\n--$bound\n";
+}
+
+sub print_http_headers_multipart_end {
+print "\n--$bound--\n";
+}
+
+sub displayhtml {
+local($buffer) = @_;
+$len = length($buffer);
+print "Content-type: text/html\n";
+print "Content-length: $len\n\n";
+print $buffer;
+}
+
+sub readfile {
+local($file) = @_;
+local(*FP, $size, $buffer, $bytes);
+($x, $x, $x, $x, $x, $x, $x, $size) = stat($file);
+$size = sprintf("%d", $size);
+open(FP, "&lt;$file");
+$bytes = sysread(FP, $buffer, $size);
+close(FP);
+return $buffer;
+}
+
+$buffer = &readfile($QS_f);
+&print_http_headers_multipart_begin;
+&displayhtml($buffer);
+
+sub mystat {
+local($file) = $_[0];
+local($time);
+
+($x, $x, $x, $x, $x, $x, $x, $x, $x, $mtime) = stat($file);
+return $mtime;
+}
+
+$mtimeL = &mystat($QS_f);
+$mtime = $mtime;
+for ($n = 0; $n &lt; $QS_n; $n++) {
+while (1) {
+ $mtime = &mystat($QS_f);
+ if ($mtime ne $mtimeL) {
+ $mtimeL = $mtime;
+ sleep(2);
+ $buffer = &readfile($QS_f);
+ &print_http_headers_multipart_next;
+ &displayhtml($buffer);
+ sleep(5);
+ $mtimeL = &mystat($QS_f);
+ last;
+ }
+ sleep($QS_s);
+}
+}
+
+&print_http_headers_multipart_end;
+
+exit(0);
+
+##EOF##
+</pre></div>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="structuredhomedirs" id="structuredhomedirs">Structured Userdirs</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>Some sites with thousands of users use a
+ structured homedir layout, <em>i.e.</em> each homedir is in a
+ subdirectory which begins (for instance) with the first
+ character of the username. So, <code>/~larry/anypath</code>
+ is <code>/home/<strong>l</strong>/larry/public_html/anypath</code>
+ while <code>/~waldo/anypath</code> is
+ <code>/home/<strong>w</strong>/waldo/public_html/anypath</code>.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We use the following ruleset to expand the tilde URLs
+ into the above layout.</p>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+RewriteRule ^/~(<strong>([a-z])</strong>[a-z0-9]+)(.*) /home/<strong>$2</strong>/$1/public_html$3
+</code></p></div>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="redirectanchors" id="redirectanchors">Redirecting Anchors</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>By default, redirecting to an HTML anchor doesn't work,
+ because mod_rewrite escapes the <code>#</code> character,
+ turning it into <code>%23</code>. This, in turn, breaks the
+ redirection.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>Use the <code>[NE]</code> flag on the
+ <code>RewriteRule</code>. NE stands for No Escape.
+ </p>
+ </dd>
+
+ <dt>Discussion:</dt>
+ <dd>This technique will of course also work with other
+ special characters that mod_rewrite, by default, URL-encodes.</dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="time-dependent" id="time-dependent">Time-Dependent Rewriting</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We wish to use mod_rewrite to serve different content based on
+ the time of day.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>There are a lot of variables named <code>TIME_xxx</code>
+ for rewrite conditions. In conjunction with the special
+ lexicographic comparison patterns <code><STRING</code>,
+ <code>>STRING</code> and <code>=STRING</code> we can
+ do time-dependent redirects:</p>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+RewriteCond %{TIME_HOUR}%{TIME_MIN} >0700<br />
+RewriteCond %{TIME_HOUR}%{TIME_MIN} <1900<br />
+RewriteRule ^foo\.html$ foo.day.html [L]<br />
+RewriteRule ^foo\.html$ foo.night.html
+</code></p></div>
+
+ <p>This provides the content of <code>foo.day.html</code>
+ under the URL <code>foo.html</code> from
+ <code>07:01-18:59</code> and at the remaining time the
+ contents of <code>foo.night.html</code>.</p>
+
+ <div class="warning"><code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>, intermediate proxies
+ and browsers may each cache responses and cause the either page to be
+ shown outside of the time-window configured.
+ <code class="module"><a href="../mod/mod_expires.html">mod_expires</a></code> may be used to control this
+ effect. You are, of course, much better off simply serving the
+ content dynamically, and customizing it based on the time of day.</div>
+
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="setenvvars" id="setenvvars">Set Environment Variables Based On URL Parts</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>At time, we want to maintain some kind of status when we
+ perform a rewrite. For example, you want to make a note that
+ you've done that rewrite, so that you can check later to see if a
+ request can via that rewrite. One way to do this is by setting an
+ environment variable.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>Use the [E] flag to set an environment variable.</p>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+RewriteRule ^/horse/(.*) /pony/$1 [E=<strong>rewritten:1</strong>]
+</code></p></div>
+
+ <p>Later in your ruleset you might check for this environment
+ variable using a RewriteCond:</p>
+
+<div class="example"><p><code>
+RewriteCond %{ENV:rewritten} =1
+</code></p></div>
+
+ </dd>
+ </dl>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/avoid.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
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 1059167 $ -->
+
+<!--
+ 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="avoid.xml.meta">
+ <parentdocument href="./">Rewrite</parentdocument>
+
+<title>Advanced Techniques with mod_rewrite</title>
+
+<summary>
+
+<p>This document supplements the <module>mod_rewrite</module>
+<a href="../mod/mod_rewrite.html">reference documentation</a>. It provides
+a few advanced techniques and tricks using mod_rewrite.</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="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="sharding">
+
+ <title>URL-based sharding accross multiple backends</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>A common technique for distributing the burden of
+ server load or storage space is called "sharding".
+ When using this method, a front-end server will use the
+ url to consistently "shard" users or objects to separate
+ backend servers.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>A mapping is maintained, from users to target servers, in
+ external map files. They look like:</p>
+
+<example>
+user1 physical_host_of_user1<br />
+user2 physical_host_of_user2<br />
+: :
+</example>
+
+ <p>We put this into a <code>map.users-to-hosts</code> file. The
+ aim is to map;</p>
+
+<example>
+/u/user1/anypath
+</example>
+
+ <p>to</p>
+
+<example>
+http://physical_host_of_user1/u/user/anypath
+</example>
+
+ <p>thus every URL path need not be valid on every backend physical
+ host. The following ruleset does this for us with the help of the map
+ files assuming that server0 is a default server which will be used if
+ a user has no entry in the map:</p>
+
+<example>
+RewriteEngine on<br />
+<br />
+RewriteMap users-to-hosts txt:/path/to/map.users-to-hosts<br />
+<br />
+RewriteRule ^/u/<strong>([^/]+)</strong>/?(.*) http://<strong>${users-to-hosts:$1|server0}</strong>/u/$1/$2
+</example>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="on-the-fly-content">
+
+ <title>On-the-fly Content-Regeneration</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We wish to dynamically generate content, but store it
+ statically once it is generated. This rule will check for the
+ existence of the static file, and if it's not there, generate
+ it. The static files can be removed periodically, if desired (say,
+ via cron) and will be regenerated on demand.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ This is done via the following ruleset:
+
+<example>
+# This example is valid in per-directory context only<br />
+RewriteCond %{REQUEST_FILENAME} <strong>!-s</strong><br />
+RewriteRule ^page\.<strong>html</strong>$ page.<strong>cgi</strong> [T=application/x-httpd-cgi,L]
+</example>
+
+ <p>Here a request for <code>page.html</code> leads to an
+ internal run of a corresponding <code>page.cgi</code> if
+ <code>page.html</code> is missing or has filesize
+ null. The trick here is that <code>page.cgi</code> is a
+ CGI script which (additionally to its <code>STDOUT</code>)
+ writes its output to the file <code>page.html</code>.
+ Once it has completed, the server sends out
+ <code>page.html</code>. When the webmaster wants to force
+ a refresh of the contents, he just removes
+ <code>page.html</code> (typically from <code>cron</code>).</p>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="load-balancing">
+
+ <title>Load Balancing</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We wish to randomly distribute load across several servers
+ using mod_rewrite.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We'll use <directive
+ module="mod_rewrite">RewriteMap</directive> and a list of servers
+ to accomplish this.</p>
+
+<example>
+RewriteEngine on<br />
+RewriteMap lb rnd:/path/to/serverlist.txt<br />
+<br />
+RewriteRule ^/(.*) http://${lb:servers}/$1 [P,L]
+</example>
+
+<p><code>serverlist.txt</code> will contain a list of the servers:</p>
+
+<example>
+## serverlist.txt<br />
+<br />
+servers one.example.com|two.example.com|three.example.com<br />
+</example>
+
+<p>If you want one particular server to get more of the load than the
+others, add it more times to the list.</p>
+
+ </dd>
+
+ <dt>Discussion</dt>
+ <dd>
+<p>Apache comes with a load-balancing module -
+<module>mod_proxy_balancer</module> - which is far more flexible and
+featureful than anything you can cobble together using mod_rewrite.</p>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="autorefresh">
+
+ <title>Document With Autorefresh</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>Wouldn't it be nice, while creating a complex web page, if
+ the web browser would automatically refresh the page every
+ time we save a new version from within our editor?
+ Impossible?</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>No! We just combine the MIME multipart feature, the
+ web server NPH feature, and the URL manipulation power of
+ <module>mod_rewrite</module>. First, we establish a new
+ URL feature: Adding just <code>:refresh</code> to any
+ URL causes the 'page' to be refreshed every time it is
+ updated on the filesystem.</p>
+
+<example>
+RewriteRule ^(/[uge]/[^/]+/?.*):refresh /internal/cgi/apache/nph-refresh?f=$1
+</example>
+
+ <p>Now when we reference the URL</p>
+
+<example>
+/u/foo/bar/page.html:refresh
+</example>
+
+ <p>this leads to the internal invocation of the URL</p>
+
+<example>
+/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html
+</example>
+
+ <p>The only missing part is the NPH-CGI script. Although
+ one would usually say "left as an exercise to the reader"
+ ;-) I will provide this, too.</p>
+
+<example><pre>
+#!/sw/bin/perl
+##
+## nph-refresh -- NPH/CGI script for auto refreshing pages
+## Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.
+##
+$| = 1;
+
+# split the QUERY_STRING variable
+@pairs = split(/&/, $ENV{'QUERY_STRING'});
+foreach $pair (@pairs) {
+($name, $value) = split(/=/, $pair);
+$name =~ tr/A-Z/a-z/;
+$name = 'QS_' . $name;
+$value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
+eval "\$$name = \"$value\"";
+}
+$QS_s = 1 if ($QS_s eq '');
+$QS_n = 3600 if ($QS_n eq '');
+if ($QS_f eq '') {
+print "HTTP/1.0 200 OK\n";
+print "Content-type: text/html\n\n";
+print "&lt;b&gt;ERROR&lt;/b&gt;: No file given\n";
+exit(0);
+}
+if (! -f $QS_f) {
+print "HTTP/1.0 200 OK\n";
+print "Content-type: text/html\n\n";
+print "&lt;b&gt;ERROR&lt;/b&gt;: File $QS_f not found\n";
+exit(0);
+}
+
+sub print_http_headers_multipart_begin {
+print "HTTP/1.0 200 OK\n";
+$bound = "ThisRandomString12345";
+print "Content-type: multipart/x-mixed-replace;boundary=$bound\n";
+&print_http_headers_multipart_next;
+}
+
+sub print_http_headers_multipart_next {
+print "\n--$bound\n";
+}
+
+sub print_http_headers_multipart_end {
+print "\n--$bound--\n";
+}
+
+sub displayhtml {
+local($buffer) = @_;
+$len = length($buffer);
+print "Content-type: text/html\n";
+print "Content-length: $len\n\n";
+print $buffer;
+}
+
+sub readfile {
+local($file) = @_;
+local(*FP, $size, $buffer, $bytes);
+($x, $x, $x, $x, $x, $x, $x, $size) = stat($file);
+$size = sprintf("%d", $size);
+open(FP, "&lt;$file");
+$bytes = sysread(FP, $buffer, $size);
+close(FP);
+return $buffer;
+}
+
+$buffer = &readfile($QS_f);
+&print_http_headers_multipart_begin;
+&displayhtml($buffer);
+
+sub mystat {
+local($file) = $_[0];
+local($time);
+
+($x, $x, $x, $x, $x, $x, $x, $x, $x, $mtime) = stat($file);
+return $mtime;
+}
+
+$mtimeL = &mystat($QS_f);
+$mtime = $mtime;
+for ($n = 0; $n &lt; $QS_n; $n++) {
+while (1) {
+ $mtime = &mystat($QS_f);
+ if ($mtime ne $mtimeL) {
+ $mtimeL = $mtime;
+ sleep(2);
+ $buffer = &readfile($QS_f);
+ &print_http_headers_multipart_next;
+ &displayhtml($buffer);
+ sleep(5);
+ $mtimeL = &mystat($QS_f);
+ last;
+ }
+ sleep($QS_s);
+}
+}
+
+&print_http_headers_multipart_end;
+
+exit(0);
+
+##EOF##
+</pre></example>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="structuredhomedirs">
+
+ <title>Structured Userdirs</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>Some sites with thousands of users use a
+ structured homedir layout, <em>i.e.</em> each homedir is in a
+ subdirectory which begins (for instance) with the first
+ character of the username. So, <code>/~larry/anypath</code>
+ is <code>/home/<strong>l</strong>/larry/public_html/anypath</code>
+ while <code>/~waldo/anypath</code> is
+ <code>/home/<strong>w</strong>/waldo/public_html/anypath</code>.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We use the following ruleset to expand the tilde URLs
+ into the above layout.</p>
+
+<example>
+RewriteEngine on<br />
+RewriteRule ^/~(<strong>([a-z])</strong>[a-z0-9]+)(.*) /home/<strong>$2</strong>/$1/public_html$3
+</example>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="redirectanchors">
+
+ <title>Redirecting Anchors</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>By default, redirecting to an HTML anchor doesn't work,
+ because mod_rewrite escapes the <code>#</code> character,
+ turning it into <code>%23</code>. This, in turn, breaks the
+ redirection.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>Use the <code>[NE]</code> flag on the
+ <code>RewriteRule</code>. NE stands for No Escape.
+ </p>
+ </dd>
+
+ <dt>Discussion:</dt>
+ <dd>This technique will of course also work with other
+ special characters that mod_rewrite, by default, URL-encodes.</dd>
+ </dl>
+
+</section>
+
+<section id="time-dependent">
+
+ <title>Time-Dependent Rewriting</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We wish to use mod_rewrite to serve different content based on
+ the time of day.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>There are a lot of variables named <code>TIME_xxx</code>
+ for rewrite conditions. In conjunction with the special
+ lexicographic comparison patterns <code><STRING</code>,
+ <code>>STRING</code> and <code>=STRING</code> we can
+ do time-dependent redirects:</p>
+
+<example>
+RewriteEngine on<br />
+RewriteCond %{TIME_HOUR}%{TIME_MIN} >0700<br />
+RewriteCond %{TIME_HOUR}%{TIME_MIN} <1900<br />
+RewriteRule ^foo\.html$ foo.day.html [L]<br />
+RewriteRule ^foo\.html$ foo.night.html
+</example>
+
+ <p>This provides the content of <code>foo.day.html</code>
+ under the URL <code>foo.html</code> from
+ <code>07:01-18:59</code> and at the remaining time the
+ contents of <code>foo.night.html</code>.</p>
+
+ <note type="warning"><module>mod_cache</module>, intermediate proxies
+ and browsers may each cache responses and cause the either page to be
+ shown outside of the time-window configured.
+ <module>mod_expires</module> may be used to control this
+ effect. You are, of course, much better off simply serving the
+ content dynamically, and customizing it based on the time of day.</note>
+
+ </dd>
+ </dl>
+
+</section>
+
+<section id="setenvvars">
+
+ <title>Set Environment Variables Based On URL Parts</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>At time, we want to maintain some kind of status when we
+ perform a rewrite. For example, you want to make a note that
+ you've done that rewrite, so that you can check later to see if a
+ request can via that rewrite. One way to do this is by setting an
+ environment variable.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>Use the [E] flag to set an environment variable.</p>
+
+<example>
+RewriteEngine on<br />
+RewriteRule ^/horse/(.*) /pony/$1 [E=<strong>rewritten:1</strong>]
+</example>
+
+ <p>Later in your ruleset you might check for this environment
+ variable using a RewriteCond:</p>
+
+<example>
+RewriteCond %{ENV:rewritten} =1
+</example>
+
+ </dd>
+ </dl>
+
+</section>
+
+</manualpage>
<?xml version="1.0" encoding="UTF-8" ?>
<!-- GENERATED FROM XML: DO NOT EDIT -->
-<metafile reference="rewrite_guide.xml">
- <basename>rewrite_guide</basename>
+<metafile reference="advanced.xml">
+ <basename>advanced</basename>
<path>/rewrite/</path>
<relpath>..</relpath>
# GENERATED FROM XML -- DO NOT EDIT
-URI: rewrite_guide.html.en
+URI: avoid.html.en
Content-Language: en
Content-type: text/html; charset=ISO-8859-1
--- /dev/null
+<?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>When not to use mod_rewrite - 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>When not to use mod_rewrite</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/rewrite/avoid.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
+perhaps one of the most important concepts about mod_rewrite - namely,
+when to avoid using it.</p>
+
+<p>mod_rewrite should be considered a last resort, when other
+alternatives are found wanting. Using it when there are simpler
+alternatives leads to configurations which are confusing, fragile, and
+hard to maintain. Understanding what other alternatives are available is
+a very important step towards mod_rewrite mastery.</p>
+
+<p>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.</p>
+
+<p>The most common situation in which <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> is
+the right tool is when the very best solution requires access to the
+server configuration files, and you don't have that access. Some
+configuration directives are only available in the server configuration
+file. So if you are in a hosting situation where you only have .htaccess
+files to work with, you may need to resort to
+<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.</p>
+
+</div>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#redirect">Simple Redirection</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#alias">URL Aliasing</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#vhosts">Virtual Hosting</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#proxy">Simple Proxying</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#setenv">Environment Variable Testing</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></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="redirect" id="redirect">Simple Redirection</a></h2>
+
+
+<p><code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> provides the <code class="directive"><a href="../mod/mod_alias.html#redirect">Redirect</a></code> and <code class="directive"><a href="../mod/mod_alias.html#redirectmatch">RedirectMatch</a></code> directives, which provide a
+means to redirect one URL to another. This kind of simple redirection of
+one URL, or a class of URLs, to somewhere else, should be accomplished
+using these directives rather than <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. <code>RedirectMatch</code>
+allows you to include a regular expression in your redirection criteria,
+providing many of the benefits of using <code>RewriteRule</code>.</p>
+
+<p>A common use for <code>RewriteRule</code> is to redirect an entire
+class of URLs. For example, all URLs in the <code>/one</code> directory
+must be redirected to <code>http://one.example.com/</code>, or perhaps
+all <code>http</code> requests must be redirected to
+<code>https</code>.</p>
+
+<p>These situations are better handled by the <code>Redirect</code>
+directive. Remember that <code>Redirect</code> preserves path
+information. That is to say, a redirect for a URL <code>/one</code> will
+also redirect all URLs under that, such as <code>/one/two.html</code>
+and <code>/one/three/four.html</code>.</p>
+
+<p>To redirect URLs under <code>/one</code> to
+<code>http://one.example.com</code>, do the following:</p>
+
+<div class="example"><p><code>
+Redirect /one/ http://one.example.com/
+</code></p></div>
+
+<p>To redirect <code>http</code> URLs to <code>https</code>, do the
+following:</p>
+
+<div class="example"><p><code>
+<VirtualHost *:80>
+ServerName www.example.com<br />
+Redirect / https://www.example.com/<br />
+</VirtualHost >
+<br />
+<VirtualHost *:443>
+ServerName www.example.com<br />
+<br />
+# ... SSL configuration goes here<br />
+</VirtualHost >
+</code></p></div>
+
+<p>The use of <code>RewriteRule</code> to perform this task may be
+appropriate if there are other <code>RewriteRule</code> directives in
+the same scope. This is because, when there are <code>Redirect</code>
+and <code>RewriteRule</code> directives in the same scope, the
+<code>RewriteRule</code> directives will run first, regardless of the
+order of appearance in the configuration file.</p>
+
+<p>In the case of the <em>http-to-https</em> redirection, the use of
+<code>RewriteRule</code> would be appropriate if you don't have access
+to the main server configuration file, and are obliged to perform this
+task in a <code>.htaccess</code> file instead.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="alias" id="alias">URL Aliasing</a></h2>
+<p>The <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> directive
+provides mapping from a URI to a directory - usually a directory outside
+of your <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>. Although it
+is possible to perform this mapping with <code>mod_rewrite</code>,
+<code>Alias</code> is the preferred method, for reasons of simplicity
+and performance.</p>
+
+<div class="example"><h3>Using Alias</h3><p><code>
+Alias /cats /var/www/virtualhosts/felines/htdocs
+</code></p></div>
+
+<p>
+The use of <code>mod_rewrite</code> to perform this mapping may be
+appropriate when you do not have access to the server configuration
+files. Alias may only be used in server or virtualhost context, and not
+in a <code>.htaccess</code> file.
+</p>
+
+<p>Symbolic links would be another way to accomplish the same thing, if
+you have <code>Options FollowSymLinks</code> enabled on your
+server.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="vhosts" id="vhosts">Virtual Hosting</a></h2>
+<p>Although it is possible to handle <a href="vhosts.html">virtual hosts
+with mod_rewrite</a>, it is seldom the right way. Creating individual
+<VirtualHost> blocks is almost always the right way to go. In the
+event that you have an enormous number of virtual hosts, consider using
+<code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> to create these hosts automatically.</p>
+
+<p>Third-party modules such as <a href="link_needed">mod_macro</a> are
+also useful for creating a large number of virtual hosts dynamically.</p>
+
+<p>Using <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> for vitualhost creation may be
+appropriate if you are using a hosting service that does not provide
+you access to the server configuration files, and you are therefore
+restricted to configuration using <code>.htaccess</code> files.</p>
+
+<p>See the <a href="vhosts.html">virtual hosts with mod_rewrite</a>
+document for more details on how you might accomplish this if it still
+seems like the right approach.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="proxy" id="proxy">Simple Proxying</a></h2>
+
+<p><code>RewriteRule</code> provides the <a href="flags.html#flag_p">[P]</a> flag to pass rewritten URIs through
+<code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>.</p>
+
+<div class="example"><p><code>
+RewriteRule ^/?images(.*) http://imageserver.local/images$1 [P]
+</code></p></div>
+
+<p>However, in many cases, when there is no actual pattern matching
+meeded, as in the example shown above, the <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> directive is a better choice.
+The example here could be rendered as:</p>
+
+<div class="example"><p><code>
+ProxyPass /images/ http://imageserver.local/images/
+</code></p></div>
+
+<p>Note that whether you use <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code>, you'll still need to use the
+<code class="directive"><a href="../mod/mod_proxy.html#proxypassreverse">ProxyPassReverse</a></code> directive to
+catch redirects issued from the back-end server:</p>
+
+<div class="example"><p><code>
+ProxyPassReverse /images/ http://imageserver.local/images/
+</code></p></div>
+
+<p>You may need to use <code>RewriteRule</code> instead when there are
+other <code>RewriteRule</code>s in effect in the same scope, as a
+<code>RewriteRule</code> will usually take effect before a
+<code>ProxyPass</code>, and so may preempt what you're trying to
+accomplish.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="setenv" id="setenv">Environment Variable Testing</a></h2>
+
+<p><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> is frequently used to take a particular
+action based on the presence or absense of a particular environment
+variable or request header. This can be done more efficiently using the
+<code class="directive"><a href="../mod/core.html#if"><If></a></code>.</p>
+
+<p>Consider, for example, the common scenario where
+<code class="directive">RewriteRule</code> is used to enforce a canonical
+hostname, such as <code>www.example.com</code> instead of
+<code>example.com</code>. This can be done using the <code class="directive"><a href="../mod/core.html#if"><If></a></code> direct, as shown here:</p>
+
+<div class="example"><p><code>
+<If "$req{Host} = 'example.com'"><br />
+RedirectMatch (.*) http://www.example.com$1
+</If>
+</code></p></div>
+
+<p>This technique can be used to take actions based on any request
+header, response header, or environment variable, replacing
+<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> in many common scenarios.</p>
+
+<p>See especially the <a href="../expr.html">expression evaluation
+documentation</a> for a overview of what types of expressions you can
+use in <If> sections, and in certain other directives.</p>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/avoid.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
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 1070886 $ -->
+
+<!--
+ 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="avoid.xml.meta">
+ <parentdocument href="./">Rewrite</parentdocument>
+
+<title>When not to use mod_rewrite</title>
+
+<summary>
+
+<p>This document supplements the <module>mod_rewrite</module>
+<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
+perhaps one of the most important concepts about mod_rewrite - namely,
+when to avoid using it.</p>
+
+<p>mod_rewrite should be considered a last resort, when other
+alternatives are found wanting. Using it when there are simpler
+alternatives leads to configurations which are confusing, fragile, and
+hard to maintain. Understanding what other alternatives are available is
+a very important step towards mod_rewrite mastery.</p>
+
+<p>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.</p>
+
+<p>The most common situation in which <module>mod_rewrite</module> is
+the right tool is when the very best solution requires access to the
+server configuration files, and you don't have that access. Some
+configuration directives are only available in the server configuration
+file. So if you are in a hosting situation where you only have .htaccess
+files to work with, you may need to resort to
+<module>mod_rewrite</module>.</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="redirect">
+<title>Simple Redirection</title>
+
+<p><module>mod_alias</module> provides the <directive
+module="mod_alias">Redirect</directive> and <directive
+module="mod_alias">RedirectMatch</directive> directives, which provide a
+means to redirect one URL to another. This kind of simple redirection of
+one URL, or a class of URLs, to somewhere else, should be accomplished
+using these directives rather than <directive
+module="mod_rewrite">RewriteRule</directive>. <code>RedirectMatch</code>
+allows you to include a regular expression in your redirection criteria,
+providing many of the benefits of using <code>RewriteRule</code>.</p>
+
+<p>A common use for <code>RewriteRule</code> is to redirect an entire
+class of URLs. For example, all URLs in the <code>/one</code> directory
+must be redirected to <code>http://one.example.com/</code>, or perhaps
+all <code>http</code> requests must be redirected to
+<code>https</code>.</p>
+
+<p>These situations are better handled by the <code>Redirect</code>
+directive. Remember that <code>Redirect</code> preserves path
+information. That is to say, a redirect for a URL <code>/one</code> will
+also redirect all URLs under that, such as <code>/one/two.html</code>
+and <code>/one/three/four.html</code>.</p>
+
+<p>To redirect URLs under <code>/one</code> to
+<code>http://one.example.com</code>, do the following:</p>
+
+<example>
+Redirect /one/ http://one.example.com/
+</example>
+
+<p>To redirect <code>http</code> URLs to <code>https</code>, do the
+following:</p>
+
+<example>
+<VirtualHost *:80>
+ServerName www.example.com<br />
+Redirect / https://www.example.com/<br />
+</VirtualHost >
+<br />
+<VirtualHost *:443>
+ServerName www.example.com<br />
+<br />
+# ... SSL configuration goes here<br />
+</VirtualHost >
+</example>
+
+<p>The use of <code>RewriteRule</code> to perform this task may be
+appropriate if there are other <code>RewriteRule</code> directives in
+the same scope. This is because, when there are <code>Redirect</code>
+and <code>RewriteRule</code> directives in the same scope, the
+<code>RewriteRule</code> directives will run first, regardless of the
+order of appearance in the configuration file.</p>
+
+<p>In the case of the <em>http-to-https</em> redirection, the use of
+<code>RewriteRule</code> would be appropriate if you don't have access
+to the main server configuration file, and are obliged to perform this
+task in a <code>.htaccess</code> file instead.</p>
+
+</section>
+
+<section id="alias"><title>URL Aliasing</title>
+<p>The <directive module="mod_alias">Alias</directive> directive
+provides mapping from a URI to a directory - usually a directory outside
+of your <directive module="core">DocumentRoot</directive>. Although it
+is possible to perform this mapping with <code>mod_rewrite</code>,
+<code>Alias</code> is the preferred method, for reasons of simplicity
+and performance.</p>
+
+<example><title>Using Alias</title>
+Alias /cats /var/www/virtualhosts/felines/htdocs
+</example>
+
+<p>
+The use of <code>mod_rewrite</code> to perform this mapping may be
+appropriate when you do not have access to the server configuration
+files. Alias may only be used in server or virtualhost context, and not
+in a <code>.htaccess</code> file.
+</p>
+
+<p>Symbolic links would be another way to accomplish the same thing, if
+you have <code>Options FollowSymLinks</code> enabled on your
+server.</p>
+</section>
+
+<section id="vhosts"><title>Virtual Hosting</title>
+<p>Although it is possible to handle <a href="vhosts.html">virtual hosts
+with mod_rewrite</a>, it is seldom the right way. Creating individual
+<VirtualHost> blocks is almost always the right way to go. In the
+event that you have an enormous number of virtual hosts, consider using
+<module>mod_vhost_alias</module> to create these hosts automatically.</p>
+
+<p>Third-party modules such as <a href="link_needed">mod_macro</a> are
+also useful for creating a large number of virtual hosts dynamically.</p>
+
+<p>Using <module>mod_rewrite</module> for vitualhost creation may be
+appropriate if you are using a hosting service that does not provide
+you access to the server configuration files, and you are therefore
+restricted to configuration using <code>.htaccess</code> files.</p>
+
+<p>See the <a href="vhosts.html">virtual hosts with mod_rewrite</a>
+document for more details on how you might accomplish this if it still
+seems like the right approach.</p>
+
+</section>
+
+<section id="proxy"><title>Simple Proxying</title>
+
+<p><code>RewriteRule</code> provides the <a
+href="flags.html#flag_p">[P]</a> flag to pass rewritten URIs through
+<module>mod_proxy</module>.</p>
+
+<example>
+RewriteRule ^/?images(.*) http://imageserver.local/images$1 [P]
+</example>
+
+<p>However, in many cases, when there is no actual pattern matching
+meeded, as in the example shown above, the <directive
+module="mod_proxy">ProxyPass</directive> directive is a better choice.
+The example here could be rendered as:</p>
+
+<example>
+ProxyPass /images/ http://imageserver.local/images/
+</example>
+
+<p>Note that whether you use <directive
+module="mod_rewrite">RewriteRule</directive> or <directive
+module="mod_proxy">ProxyPass</directive>, you'll still need to use the
+<directive module="mod_proxy">ProxyPassReverse</directive> directive to
+catch redirects issued from the back-end server:</p>
+
+<example>
+ProxyPassReverse /images/ http://imageserver.local/images/
+</example>
+
+<p>You may need to use <code>RewriteRule</code> instead when there are
+other <code>RewriteRule</code>s in effect in the same scope, as a
+<code>RewriteRule</code> will usually take effect before a
+<code>ProxyPass</code>, and so may preempt what you're trying to
+accomplish.</p>
+
+</section>
+
+<section id="setenv"><title>Environment Variable Testing</title>
+
+<p><module>mod_rewrite</module> is frequently used to take a particular
+action based on the presence or absense of a particular environment
+variable or request header. This can be done more efficiently using the
+<directive module="core" type="section">If</directive>.</p>
+
+<p>Consider, for example, the common scenario where
+<directive>RewriteRule</directive> is used to enforce a canonical
+hostname, such as <code>www.example.com</code> instead of
+<code>example.com</code>. This can be done using the <directive
+module="core" type="section">If</directive> direct, as shown here:</p>
+
+<example>
+<If "$req{Host} = 'example.com'"><br />
+RedirectMatch (.*) http://www.example.com$1
+</If>
+</example>
+
+<p>This technique can be used to take actions based on any request
+header, response header, or environment variable, replacing
+<module>mod_rewrite</module> in many common scenarios.</p>
+
+<p>See especially the <a href="../expr.html">expression evaluation
+documentation</a> for a overview of what types of expressions you can
+use in <If> sections, and in certain other directives.</p>
+
+</section>
+
+</manualpage>
+
<?xml version="1.0" encoding="UTF-8" ?>
<!-- GENERATED FROM XML: DO NOT EDIT -->
-<metafile reference="rewrite_intro.xml">
- <basename>rewrite_intro</basename>
+<metafile reference="avoid.xml">
+ <basename>avoid</basename>
<path>/rewrite/</path>
<relpath>..</relpath>
--- /dev/null
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: flags.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1
+
+URI: flags.html.fr
+Content-Language: fr
+Content-type: text/html; charset=ISO-8859-1
--- /dev/null
+<?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>RewriteRule Flags - 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>RewriteRule Flags</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English"> en </a> |
+<a href="../fr/rewrite/flags.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
+</div>
+
+<p>This document discusses the flags which are available to the
+<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive,
+providing detailed explanations and examples.</p>
+</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="#flag_b">B (escape backreferences)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_c">C|chain</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_co">CO|cookie</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_dpi">DPI|discardpathinfo</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_e">E|env</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_f">F|forbidden</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_g">G|gone</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_h">H|handler</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_l">L|last</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_n">N|next</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_nc">NC|nocase</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_ne">NE|noescape</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_ns">NS|nosubreq</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_p">P|proxy</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_pt">PT|passthrough</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_qsa">QSA|qsappend</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_qsd">QSD|qsdiscard</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_r">R|redirect</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_s">S|skip</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_t">T|type</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="introduction" id="introduction">Introduction</a></h2>
+<p>A <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> can have
+its behavior modified by one or more flags. Flags are included in
+square brackets at the end of the rule, and multiple flags are separated
+by commas.</p>
+<div class="example"><p><code>
+RewriteRule pattern target [Flag1,Flag2,Flag3]
+</code></p></div>
+
+<p>The flags all have a short form, such as <code>CO</code>, as well as
+a longer form, such as <code>cookie</code>. Some flags take one or more
+arguments. Flags are not case sensitive.</p>
+
+<p>Each flag (with a few exceptions)
+has a long and short form. While it is most common to use
+the short form, it is recommended that you familiarize yourself with the
+long form, so that you remember what each flag is supposed to do.</p>
+
+<p>Flags that alter metadata associated with the request (T=, H=, E=)
+have no affect in per-directory and htaccess context, when a substitution
+(other than '-') is performed during the same round of rewrite processing.
+</p>
+
+<p>Presented here are each of the available flags, along with an example
+of how you might use them.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_b" id="flag_b">B (escape backreferences)</a></h2>
+<p>The [B] flag instructs <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to escape non-alphanumeric
+characters before applying the transformation.
+</p>
+
+<p><code>mod_rewrite</code> has to unescape URLs before mapping them,
+so backreferences will be unescaped at the time they are applied.
+Using the B flag, non-alphanumeric characters in backreferences
+will be escaped. For example, consider the rule:</p>
+
+<div class="example"><p><code>
+RewriteRule ^(/.*)$ /index.php?show=$1
+</code></p></div>
+
+<p>This will map <code>/C++</code> to
+<code>/index.php?show=/C++</code>. But it will also map
+<code>/C%2b%2b</code> to <code>/index.php?show=/C++</code>, because
+the <code>%2b</code> has been unescaped. With the B flag, it will
+instead map to <code>/index.php?show=/C%2b%2b</code>.</p>
+
+<p>This escaping is particularly necessary in a proxy situation,
+when the backend may break if presented with an unescaped URL.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_c" id="flag_c">C|chain</a></h2>
+<p>The [C] or [chain] flag indicates that the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is chained to the next
+rule. That is, if the rule matches, then it is processed as usual and
+control moves on to the next rule. However, if it does not match, then
+the next rule, and any other rules that are chained together, will be
+skipped.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_co" id="flag_co">CO|cookie</a></h2>
+<p>The [CO], or [cookie] flag, allows you to set a cookie when a
+particular <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>
+matches. The argument consists of three required fields and five optional
+fields.</p>
+
+<p>The full syntax for the flag, including all attributes, is as
+follows:</p>
+
+<div class="example"><p><code>
+[CO=NAME:VALUE:domain:lifetime:path:secure:httponly]
+</code></p></div>
+
+<p>You must declare a name and value for the cookie to be set.</p>
+
+<p>You may optionally also set the following values:</p>
+
+<dl>
+<dt>Domain</dt>
+<dd>The domain for which you want the cookie to be valid. This may be a
+hostname, such as <code>www.example.com</code>, or it may be a domain,
+such as <code>.example.com</code>. It must be at least two parts
+separated by a dot. That is, it may not be merely <code>.com</code> or
+<code>.net</code>. Cookies of that kind are forbidden by the cookie
+security model.</dd>
+<dd>The default value for the domain is the current domain.</dd>
+
+<dt>Lifetime</dt>
+<dd>The time for which the cookie will persist, in minutes.</dd>
+<dd>A value of 0 indicates that the cookie will persist only for the
+current browser session. This is the default value if none is
+specified.</dd>
+
+<dt>Path</dt>
+<dd>The path, on the current website, for which the cookie is valid,
+such as <code>/customers/</code> or <code>/files/download/</code>.</dd>
+<dd>By default, this is set to <code>/</code> - that is, the entire
+website.</dd>
+
+<dt>Secure</dt>
+<dd>If set to <code>secure</code>, <code>true</code>, or <code>1</code>,
+the cookie will only be permitted to be translated via secure (https)
+connections.</dd>
+
+<dt>httponly</dt>
+<dd>If set to <code>HttpOnly</code>, <code>true</code>, or
+<code>1</code>, the cookie will have the <code>HttpOnly</code> flag set,
+which means that the cookie will be inaccessible to JavaScript code on
+browsers that support this feature.</dd>
+</dl>
+
+<p>Several examples are offered here:</p>
+
+<div class="example"><p><code>
+RewriteEngine On<br />
+RewriteRule ^/index\.html - [CO=frontdoor:yes:.example.com:1440:/]
+</code></p></div>
+
+<p>In the example give, the rule doesn't rewrite the request.
+The "-" rewrite target tells mod_rewrite to pass the request
+through unchanged. Instead, it sets a cookie
+called 'frontdoor' to a value of 'yes'. The cookie is valid for any host
+in the <code>.example.com</code> domain. It will be set to expire in 1440
+minutes (24 hours) and will be returned for all URIs.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_dpi" id="flag_dpi">DPI|discardpathinfo</a></h2>
+<p>The DPI flag causes the PATH_INFO portion of the rewritten URI to be
+discarded.</p>
+<p>This flag is available in version 2.2.12 and later.</p>
+<p>In per-directory context, the URI each <code class="directive">RewriteRule</code>
+compares against is the concatenation of the current values of the URI
+and PATH_INFO.</p>
+
+<p>The current URI can be the initial URI as requested by the client, the
+result of a previous round of mod_rewrite processing, or the result of
+a prior rule in the current round of mod_rewrite processing.</p>
+
+<p>In contrast, the PATH_INFO that is appended to the URI before each
+rule reflects only the value of PATH_INFO before this round of
+mod_rewrite processing. As a consequence, if large portions
+of the URI are matched and copied into a substitution in multiple
+<code class="directive">RewriteRule</code> directives, without regard for
+which parts of the URI came from the current PATH_INFO, the final
+URI may have multiple copies of PATH_INFO appended to it.</p>
+
+<p>Use this flag on any substitution where the PATH_INFO that resulted
+from the previous mapping of this request to the filesystem is not of
+interest. This flag permanently forgets the PATH_INFO established
+before this round of mod_rewrite processing began. PATH_INFO will
+not be recalculated until the current round of mod_rewrite processing
+completes. Subsequent rules during this round of processing will see
+only the direct result of substitutions, without any PATH_INFO
+appended.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_e" id="flag_e">E|env</a></h2>
+<p>With the [E], or [env] flag, you can set the value of an environment
+variable. Note that some environment variables may be set after the rule
+is run, thus unsetting what you have set. See <a href="../env.html">the
+Environment Variables document</a> for more details on how Environment
+variables work.</p>
+
+<p>The full syntax for this flag is:</p>
+
+<div class="example"><p><code>
+[E=VAR:VAL]
+[E=!VAR]
+</code></p></div>
+
+<p><code>VAL</code> may contain backreferences (<code>$N</code> or
+<code>%N</code>) which will be expanded.</p>
+
+<p>Using the short form</p>
+
+<div class="example"><p><code>
+[E=VAR]
+</code></p></div>
+
+<p>you can set the environment variable named <code>VAR</code> to an
+empty value.</p>
+
+<p>The form</p>
+
+<div class="example"><p><code>
+[E=!VAR]
+</code></p></div>
+
+<p>allows to unset a previously set environment variable named
+<code>VAR</code>.</p>
+
+<p>Environment variables can then be used in a variety of
+contexts, including CGI programs, other RewriteRule directives, or
+CustomLog directives.</p>
+
+<p>The following example sets an environment variable called 'image' to a
+value of '1' if the requested URI is an image file. Then, that
+environment variable is used to exclude those requests from the access
+log.</p>
+
+<div class="example"><p><code>
+RewriteRule \.(png|gif|jpg) - [E=image:1]<br />
+CustomLog logs/access_log combined env=!image
+</code></p></div>
+
+<p>Note that this same effect can be obtained using <code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code>. This technique is offered as
+an example, not as a recommendation.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_f" id="flag_f">F|forbidden</a></h2>
+<p>Using the [F] flag causes the server to return a 403 Forbidden status
+code to the client. While the same behavior can be accomplished using
+the <code class="directive"><a href="../mod/mod_access.html#deny">Deny</a></code> directive, this
+allows more flexibility in assigning a Forbidden status.</p>
+
+<p>The following rule will forbid <code>.exe</code> files from being
+downloaded from your server.</p>
+
+<div class="example"><p><code>
+RewriteRule \.exe - [F]
+</code></p></div>
+
+<p>This example uses the "-" syntax for the rewrite target, which means
+that the requested URI is not modified. There's no reason to rewrite to
+another URI, if you're going to forbid the request.</p>
+
+<p>When using [F], an [L] is implied - that is, the response is returned
+immediately, and no further rules are evaluated.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_g" id="flag_g">G|gone</a></h2>
+<p>The [G] flag forces the server to return a 410 Gone status with the
+response. This indicates that a resource used to be available, but is no
+longer available.</p>
+
+<p>As with the [F] flag, you will typically use the "-" syntax for the
+rewrite target when using the [G] flag:</p>
+
+<div class="example"><p><code>
+RewriteRule oldproduct - [G,NC]
+</code></p></div>
+
+<p>When using [F], an [L] is implied - that is, the response is returned
+immediately, and no further rules are evaluated.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_h" id="flag_h">H|handler</a></h2>
+<p>Forces the resulting request to be handled with the specified
+handler. For example, one might use this to force all files without a
+file extension to be parsed by the php handler:</p>
+
+<div class="example"><p><code>
+RewriteRule !\. - [H=application/x-httpd-php]
+</code></p></div>
+
+<p>
+The regular expression above - <code>!\.</code> - will match any request
+that does not contain the literal <code>.</code> character.
+</p>
+
+<p>This can be also used to force the handler based on some conditions.
+For example, the following snippet used in per-server context allows
+<code>.php</code> files to be <em>displayed</em> by <code>mod_php</code>
+if they are requested with the <code>.phps</code> extension:</p>
+
+<div class="example"><p><code>
+RewriteRule ^(/source/.+\.php)s$ $1 [H=application/x-httpd-php-source]
+</code></p></div>
+
+<p>The regular expression above - <code>^(/source/.+\.php)s$</code> - will
+match any request that starts with <code>/source/</code> followed by 1 or
+n characters followed by <code>.phps</code> literally. The backreference
+$1 referrers to the captured match within parenthesis of the regular
+expression.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_l" id="flag_l">L|last</a></h2>
+<p>The [L] flag causes <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to stop processing
+the rule set. In most contexts, this means that if the rule matches, no
+further rules will be processed. This corresponds to the
+<code>last</code> command in Perl, or the <code>break</code> command in
+C. Use this flag to indicate that the current rule should be applied
+immediately without considering further rules.</p>
+
+<p>If you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> in either
+<code>.htaccess</code> files or in
+<code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> sections,
+it is important to have some understanding of how the rules are
+processed. The simplified form of this is that once the rules have been
+processed, the rewritten request is handed back to the URL parsing
+engine to do what it may with it. It is possible that as the rewritten
+request is handled, the <code>.htaccess</code> file or
+<code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section
+may be encountered again, and thus the ruleset may be run again from the
+start. Most commonly this will happen if one of the rules causes a
+redirect - either internal or external - causing the request process to
+start over.</p>
+
+<p>It is therefore important, if you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives in one of these
+contexts, that you take explicit steps to avoid rules looping, and not
+count solely on the [L] flag to terminate execution of a series of
+rules, as shown below.</p>
+
+<p> An alternative flag, [END], can be used to terminate not only the
+current round of rewrite processing but prevent any subsequent
+rewrite processing from occuring in per-directory (htaccess)
+context. This does not apply to new requests resulting from external
+redirects.</p>
+
+<p>The example given here will rewrite any request to
+<code>index.php</code>, giving the original request as a query string
+argument to <code>index.php</code>, however, the <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> ensures that if the request
+is already for <code>index.php</code>, the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> will be skipped.</p>
+
+<div class="example"><p><code>
+RewriteBase /<br />
+RewriteCond %{REQUEST_URI} !=/index.php<br />
+RewriteRule ^(.*) /index.php?req=$1 [L,PT]
+</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="flag_n" id="flag_n">N|next</a></h2>
+<p>
+The [N] flag causes the ruleset to start over again from the top, using
+the result of the ruleset so far as a starting point. Use
+with extreme caution, as it may result in loop.
+</p>
+<p>
+The [Next] flag could be used, for example, if you wished to replace a
+certain string or letter repeatedly in a request. The example shown here
+will replace A with B everywhere in a request, and will continue doing
+so until there are no more As to be replaced.
+</p>
+
+<div class="example"><p><code>
+RewriteRule (.*)A(.*) $1B$2 [N]
+</code></p></div>
+
+<p>You can think of this as a <code>while</code> loop: While this
+pattern still matches (i.e., while the URI still contains an
+<code>A</code>), perform this substitution (i.e., replace the
+<code>A</code> with a <code>B</code>).</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_nc" id="flag_nc">NC|nocase</a></h2>
+<p>Use of the [NC] flag causes the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be matched in a
+case-insensitive manner. That is, it doesn't care whether letters appear
+as upper-case or lower-case in the matched URI.</p>
+
+<p>In the example below, any request for an image file will be proxied
+to your dedicated image server. The match is case-insensitive, so that
+<code>.jpg</code> and <code>.JPG</code> files are both acceptable, for
+example.</p>
+
+<div class="example"><p><code>
+RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC]
+</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="flag_ne" id="flag_ne">NE|noescape</a></h2>
+<p>By default, special characters, such as <code>&</code> and
+<code>?</code>, for example, will be converted to their hexcode
+equivalent. Using the [NE] flag prevents that from happening.
+</p>
+
+<div class="example"><p><code>
+RewriteRule ^/anchor/(.+) /bigpage.html#$1 [NE,R]
+</code></p></div>
+
+<p>
+The above example will redirect <code>/anchor/xyz</code> to
+<code>/bigpage.html#xyz</code>. Omitting the [NE] will result in the #
+being converted to its hexcode equivalent, <code>%23</code>, which will
+then result in a 404 Not Found error condition.
+</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_ns" id="flag_ns">NS|nosubreq</a></h2>
+<p>Use of the [NS] flag prevents the rule from being used on
+subrequests. For example, a page which is included using an SSI (Server
+Side Include) is a subrequest, and you may want to avoid rewrites
+happening on those subrequests. Also, when <code class="module"><a href="../mod/mod_dir.html">mod_dir</a></code>
+tries to find out information about possible directory default files
+(such as <code>index.html</code> files), this is an internal
+subrequest, and you often want to avoid rewrites on such subrequests.
+On subrequests, it is not always useful, and can even cause errors, if
+the complete set of rules are applied. Use this flag to exclude
+problematic rules.</p>
+
+<p>To decide whether or not to use this rule: if you prefix URLs with
+CGI-scripts, to force them to be processed by the CGI-script, it's
+likely that you will run into problems (or significant overhead)
+on sub-requests. In these cases, use this flag.</p>
+
+<p>
+Images, javascript files, or css files, loaded as part of an HTML page,
+are not subrequests - the browser requests them as separate HTTP
+requests.
+</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_p" id="flag_p">P|proxy</a></h2>
+<p>Use of the [P] flag causes the request to be handled by
+<code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, and handled via a proxy request. For
+example, if you wanted all image requests to be handled by a back-end
+image server, you might do something like the following:</p>
+
+<div class="example"><p><code>
+RewriteRule (.*)\.(jpg|gif|png) http://images.example.com$1.$2 [P]
+</code></p></div>
+
+<p>Use of the [P] flag implies [L] - that is, the request is immediately
+pushed through the proxy, and any following rules will not be
+considered.</p>
+
+<p>
+You must make sure that the substitution string is a valid URI
+(typically starting with <code>http://</code><em>hostname</em>) which can be
+handled by the <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>. If not, you will get an
+error from the proxy module. Use this flag to achieve a
+more powerful implementation of the <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> directive,
+to map remote content into the namespace of the local server.</p>
+
+<p>Note: <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> must be enabled in order
+to use this flag.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_pt" id="flag_pt">PT|passthrough</a></h2>
+
+<p>
+The target (or substitution string) in a RewriteRule is assumed to be a
+file path, by default. The use of the [PT] flag causes it to be treated
+as a URI instead. That is to say, the
+use of the [PT] flag causes the result of the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be passed back through
+URL mapping, so that location-based mappings, such as <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>, <code class="directive"><a href="../mod/core.html#redirect">Redirect</a></code>, or <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>, for example, might have a
+chance to take effect.
+</p>
+
+<p>
+If, for example, you have an
+<code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>
+for /icons, and have a <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> pointing there, you should
+use the [PT] flag to ensure that the
+<code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> is evaluated.
+</p>
+
+<div class="example"><p><code>
+Alias /icons /usr/local/apache/icons<br />
+RewriteRule /pics/(.+)\.jpg /icons/$1.gif [PT]
+</code></p></div>
+
+<p>
+Omission of the [PT] flag in this case will cause the Alias to be
+ignored, resulting in a 'File not found' error being returned.
+</p>
+
+<p>The <code>PT</code> flag implies the <code>L</code> flag:
+rewriting will be stopped in order to pass the request to
+the next phase of processing.</p>
+
+<p>Note that the <code>PT</code> flag is implied in per-directory
+contexts such as
+<code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> sections
+or in <code>.htaccess</code> files. The only way to circumvent that
+is to rewrite to <code>-</code>.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_qsa" id="flag_qsa">QSA|qsappend</a></h2>
+<p>
+When the replacement URI contains a query string, the default behavior
+of <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is to discard
+the existing query string, and replace it with the newly generated one.
+Using the [QSA] flag causes the query strings to be combined.
+</p>
+
+<p>Consider the following rule:</p>
+
+<div class="example"><p><code>
+RewriteRule /pages/(.+) /page.php?page=$1 [QSA]
+</code></p></div>
+
+<p>With the [QSA] flag, a request for <code>/pages/123?one=two</code> will be
+mapped to <code>/page.php?page=123&one=two</code>. Without the [QSA]
+flag, that same request will be mapped to
+<code>/page.php?page=123</code> - that is, the existing query string
+will be discarded.
+</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_qsd" id="flag_qsd">QSD|qsdiscard</a></h2>
+<p>
+When the requested URI contains a query string, and the target URI does
+not, the default behavior of <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is to copy that query
+string to the target URI. Using the [QSD] flag causes the query string
+to be discarded.
+</p>
+
+<p>This flag is available in version 2.4.0 and later.</p>
+
+<p>
+Using [QSD] and [QSA] together will result in [QSD] taking precedence.
+</p>
+
+<p>
+If the target URI has a query string, the default behavior will be
+observed - that is, the original query string will be discarded and
+replaced with the query string in the <code>RewriteRule</code> target
+URI.
+</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_r" id="flag_r">R|redirect</a></h2>
+<p>
+Use of the [R] flag causes a HTTP redirect to be issued to the browser.
+If a fully-qualified URL is specified (that is, including
+<code>http://servername/</code>) then a redirect will be issued to that
+location. Otherwise, the current protocol, servername, and port number
+will be used to generate the URL sent with the redirect.
+</p>
+
+<p>
+<em>Any</em> valid HTTP response status code may be specified,
+using the syntax [R=305], with a 302 status code being used by
+default if none is specified. The status code specified need not
+necessarily be a redirect (3xx) status code.
+</p>
+
+<p>If a status code is outside the redirect range (300-399) then the
+substitution string is dropped entirely, and rewriting is stopped as if
+the <code>L</code> were used.</p>
+
+<p>In addition to response status codes, you may also specify redirect
+status using their symbolic names: <code>temp</code> (default),
+<code>permanent</code>, or <code>seeother</code>.</p>
+
+<p>
+You will almost always want to use [R] in conjunction with [L] (that is,
+use [R,L]) because on its own, the [R] flag prepends
+<code>http://thishost[:thisport]</code> to the URI, but then passes this
+on to the next rule in the ruleset, which can often result in 'Invalid
+URI in request' warnings.
+</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_s" id="flag_s">S|skip</a></h2>
+<p>The [S] flag is used to skip rules that you don't want to run. This
+can be thought of as a <code>goto</code> statement in your rewrite
+ruleset. In the following example, we only want to run the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> if the requested URI
+doesn't correspond with an actual file.</p>
+
+<div class="example"><p><code>
+# Is the request for a non-existent file?<br />
+RewriteCond %{REQUEST_FILENAME} !-f<br />
+RewriteCond %{REQUEST_FILENAME} !-d<br />
+# If so, skip these two RewriteRules<br />
+RewriteRule .? - [S=2]<br />
+<br />
+RewriteRule (.*\.gif) images.php?$1<br />
+RewriteRule (.*\.html) docs.php?$1
+</code></p></div>
+
+<p>This technique is useful because a <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> only applies to the
+<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> immediately
+following it. Thus, if you want to make a <code>RewriteCond</code> apply
+to several <code>RewriteRule</code>s, one possible technique is to
+negate those conditions and use a [Skip] flag. So, you can
+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.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_t" id="flag_t">T|type</a></h2>
+<p>Sets the MIME type with which the resulting response will be
+sent. This has the same effect as the <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> directive.</p>
+
+<p>For example, you might use the following technique to serve Perl
+source code as plain text, if requested in a particular way:</p>
+
+<div class="example"><p><code>
+# Serve .pl files as plain text<br />
+RewriteRule \.pl$ - [T=text/plain]
+</code></p></div>
+
+<p>Or, perhaps, if you have a camera that produces jpeg images without
+file extensions, you could force those images to be served with the
+correct MIME type by virtue of their file names:</p>
+
+<div class="example"><p><code>
+# Files with 'IMG' in the name are jpg images.<br />
+RewriteRule IMG - [T=image/jpg]
+</code></p></div>
+
+<p>Please note that this is a trivial example, and could be better done
+using <code class="directive"><a href="../mod/core.html#filesmatch"><FilesMatch></a></code>
+instead. Always consider the alternate
+solutions to a problem before resorting to rewrite, which will
+invariably be a less efficient solution than the alternatives.</p>
+
+<p>
+If used in per-directory context, use only <code>-</code> (dash)
+as the substitution <em>for the entire round of mod_rewrite processing</em>,
+otherwise the MIME-type set with this flag is lost due to an internal
+re-processing (including subsequent rounds of mod_rewrite processing).
+The <code>L</code> flag can be useful in this context to end the
+<em>current</em> round of mod_rewrite processing.</p>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English"> en </a> |
+<a href="../fr/rewrite/flags.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
--- /dev/null
+<?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>Les drapeaux de réécriture - 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>Les drapeaux de réécriture</h1>
+<div class="toplang">
+<p><span>Langues Disponibles: </span><a href="../en/rewrite/flags.html" hreflang="en" rel="alternate" title="English"> en </a> |
+<a href="../fr/rewrite/flags.html" title="Français"> fr </a></p>
+</div>
+
+<p>Ce document décrit les drapeaux disponibles dans la directive
+<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>, en fournissant
+des explications détaillées et des exemples.</p>
+</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="#flag_b">B (échappement dans les références arrières)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_c">C|chain</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_co">CO|cookie</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_dpi">DPI|discardpathinfo</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_e">E|env</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_f">F|forbidden</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_g">G|gone</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_h">H|handler</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_l">L|last</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_n">N|next</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_nc">NC|nocase</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_ne">NE|noescape</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_ns">NS|nosubreq</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_p">P|proxy</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_pt">PT|passthrough</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_qsa">QSA|qsappend</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_qsd">QSD|qsdiscard</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_r">R|redirect</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_s">S|skip</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flag_t">T|type</a></li>
+</ul><h3>Voir aussi</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Documentation du module</a></li><li><a href="intro.html">Introduction à mod_rewrite</a></li><li><a href="remapping.html">Redirection and 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="introduction" id="introduction">Introduction</a></h2>
+<p>Le comportement d'une directive <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> peut être modifié par un ou
+plusieurs drapeaux. Les drapeaux sont situés en fin de règle, entourés
+de crochets, et séparés le cas échéant par des virgules.</p>
+<div class="example"><p><code>
+RewriteRule modèle cible [drapeau1,drapeau2,drapeau3]
+</code></p></div>
+
+<p>Les drapeaux ont tous une forme courte, comme <code>CO</code>, ainsi
+qu'une forme longue, comme <code>cookie</code>. Certains drapeaux
+peuvent avoir un ou plusieurs arguments. Les drapeaux sont insensibles à
+la casse.</p>
+
+<p>Chaque drapeau (à quelques exceptions près) possède une forme longue et une forme courte. Bien que
+la forme courte soit la plus couramment utilisée, nous vous recommandons
+de vous familiariser avec les drapeaux sous leur forme longue, afin de
+bien mémoriser ce que chaque drapeau est supposé faire.</p>
+
+<p>Les drapeaux qui modifient les métadonnées associées à la requête
+(T=, H=, E=) n'ont aucun effet dans un contexte de répertoire ou de
+fichier htaccess, lorsqu'une substitution (autre que '-') est effectuée
+au cours de la même passe du processus de réécriture.
+</p>
+
+<p>Chaque drapeau disponible est présenté ici, avec un exemple
+d'utilisation.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_b" id="flag_b">B (échappement dans les références arrières)</a></h2>
+<p>Avec le drapeau [B], la directive <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> échappe les caractères
+non-alphanumériques avant d'appliquer la transformation.</p>
+
+<p><code>mod_rewrite</code> doit supprimer les séquences d'échappement
+des URLs avant leur
+mise en correspondance avec le système de fichiers ; les séquences
+d'échappement sont donc supprimées des références arrières au moment où
+ces dernières sont appliquées. Avec le drapeau B, les caractères
+non-alphanumériques des références arrières seront échappés. Considérons
+par exemple cette règle :</p>
+
+<div class="example"><p><code>
+RewriteRule ^(/.*)$ /index.php?show=$1
+</code></p></div>
+
+<p>Avec cet exemple, <code>/C++</code> sera réécrit en
+<code>/index.php?show=/C++</code>. Mais <code>/C%2b%2b</code> sera lui
+aussi réécrit en <code>/index.php?show=/C++</code>, car le caractère
+<code>%2b</code> aura été "déséchappé". Avec le drapeau B par contre,
+<code>/C%2b%2b</code> sera réécrit en
+<code>/index.php?show=/C%2b%2b</code>.</p>
+
+<p>Ce processus d'échappement est en particulier nécessaire dans le
+contexte d'un mandataire, où l'accès au serveur d'arrière-plan échouera
+si on présente à ce dernier une URL non échappée.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_c" id="flag_c">C|chain</a></h2>
+<p>Le drapeau [C] ou [chain] indique que la règle <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> est chaînée avec la
+suivante. Autrement dit, si la règle s'applique, elle est traitée
+normalement et passe le contrôle à la règle suivante. Par contre, si
+elle ne s'applique pas, la règle suivante, ainsi que toutes les règles
+chaînées qui suivent, seront sautées.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_co" id="flag_co">CO|cookie</a></h2>
+<p>Le drapeau [CO], ou [cookie], vous permet de définir un cookie
+lorsqu'une règle <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>
+s'applique. Il possède trois arguments obligatoires et
+cinq arguments optionnels.</p>
+
+<p>La syntaxe complète de ce drapeau, avec tous ses attributs, est la
+suivante :</p>
+
+<div class="example"><p><code>
+[CO=NAME:VALUE:domain:lifetime:path:secure:httponly]
+</code></p></div>
+
+<p>Vous devez déclarer un nom et une valeur pour que le cookie puisse
+être défini.</p>
+
+<p>Vous pouvez aussi définir les valeurs suivantes :</p>
+
+<dl>
+<dt>Domain</dt>
+<dd>Le domaine pour lequel vous souhaitez que le cookie soit valide. Ce
+peut être un nom de serveur, comme <code>www.example.com</code>, ou un
+domaine, comme <code>.example.com</code>. Il doit comporter au moins
+deux parties séparées par un point. C'est à dire que vous ne pouvez pas
+utiliser les valeurs <code>.com</code> ou <code>.net</code>. En effet,
+ce style de cookie est interdit par le modèle de sécurité des cookies.</dd>
+<dd>La valeur par défaut est le domaine courant.</dd>
+
+<dt>Lifetime</dt>
+<dd>La durée de vie du cookie, en minutes.</dd>
+<dd>Une valeur de 0 indique une durée de vie correspondant à la session
+courante du navigateur. Il s'agit de la valeur par défaut.</dd>
+
+<dt>Path</dt>
+<dd>Le chemin, sur le site web concerné, pour lequel le cookie est
+valide, du style <code>/clients/</code> or
+<code>/fichiers/telechargement/</code>.</dd>
+<dd>La valeur par défaut est <code>/</code> - c'est à dire l'ensemble du
+site web.</dd>
+
+<dt>Secure</dt>
+<dd>Si cet argument a pour valeur <code>secure</code>,
+<code>true</code>, ou <code>1</code>, le cookie ne pourra être transmis
+que dans le cadre d'une connexion sécurisée (https).</dd>
+
+<dt>httponly</dt>
+<dd>Si cet argument a pour valeur <code>HttpOnly</code>,
+<code>true</code>, ou <code>1</code>, le cookie aura son drapeau
+<code>HttpOnly</code> activé, ce qui signifie qu'il sera inaccessible au
+code JavaScript pour les navigateurs qui supportent cette
+fonctionnalité.</dd>
+</dl>
+
+<p>Voici un exemple :</p>
+
+<div class="example"><p><code>
+RewriteEngine On<br />
+RewriteRule ^/index\.html - [CO=frontdoor:yes:.example.org:1440:/]
+</code></p></div>
+
+<p>Dans l'exemple ci-dessus, la règle ne réécrit
+pas la requête. La cible de réécriture "-"
+indique à mod_rewrite de transmettre la requête sans
+modification. Par contre, il
+définit un cookie nommé 'frontdoor' avec une valeur 'yes'. Le cookie est
+valide pour tout hôte situé dans le domaine <code>.example.org</code>. Sa
+durée de vie est limitée à 1440 minutes (24 heures), et il sera renvoyé
+pour tous les URIs.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_dpi" id="flag_dpi">DPI|discardpathinfo</a></h2>
+<p>Avec le drapeau DPI, la partie PATH_INFO de l'URI
+réécrit est supprimée.</p>
+<p>Ce drapeau est disponible dans les versions 2.2.12 et supérieures.</p>
+<p>Dans un contexte de répertoire, l'URI mis en comparaison par chaque
+règle <code class="directive">RewriteRule</code> est la concaténation des
+valeurs courantes de l'URI et de PATH_INFO.</p>
+
+<p>L'URI courant peut être l'URI initial tel qu'il a été fourni par le
+client, le résultat d'une passe précédente du processus de réécriture,
+ou le résultat de la règle précédente dans le processus courant de
+réécriture.</p>
+
+<p>Par contre, la partie PATH_INFO ajoutée à l'URI avant chaque règle ne
+reflète que la valeur de PATH_INFO avant la passe courante du processus
+de réécriture. En conséquence, si de larges portions de l'URI
+correspondent et sont traduites via plusieurs directives
+<code class="directive">RewriteRule</code>, sans prendre en compte
+quelles parties de l'URI provenaient du PATH_INFO courant, l'URI final
+pourra se voir ajouter plusieurs copies de PATH_INFO.</p>
+
+<p>Utilisez ce drapeau pour toute substitution où la présence du PATH_INFO qui
+résultait de la mise en correspondance précédente de cette requête avec
+le système de fichier n'est pas nécessaire. Avec ce drapeau, le
+PATH_INFO établi avant que cette passe du processus de réécriture ne
+débute est oublié. PATH_INFO ne sera pas recalculé tant que la passe
+courante du processus de réécriture ne sera pas achevée. Les règles
+suivantes de cette passe ne verront que le résultat direct des
+substitutions, sans aucun PATH_INFO ajouté.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_e" id="flag_e">E|env</a></h2>
+<p>Avec le drapeau [E], ou [env], vous pouvez définir la valeur d'une
+variable d'environnement. Notez que certaines variables d'environnement
+peuvent être définies après le traitement de la règle, annulant par
+la-même ce que vous avez défini. Voir le <a href="../env.html">document
+sur les variables d'environnement</a> pour plus de détails sur le
+fonctionnement des variables d'environnement.</p>
+
+<p>La syntaxe complète pour ce drapeau est :</p>
+
+<div class="example"><p><code>
+[E=!VAR]
+</code></p></div>
+
+<p><code>VAL</code> peut comporter des références arrières
+(<code>$N</code> ou <code>%N</code>) qui seront développées.</p>
+
+<p>En utilisant la version courte</p>
+
+<div class="example"><p><code>
+[E=VAR]
+</code></p></div>
+
+<p>vous pouvez définir la variable d'environnement nommée
+<code>VAR</code> avec une valeur vide.</p>
+
+<p>La forme</p>
+
+<div class="example"><p><code>
+[E=!VAR]
+</code></p></div>
+
+<p>permet d'annuler la définition de la variable <code>VAR</code>.</p>
+
+<p>Les variables d'environnement s'emploient dans différents contextes,
+comme les programmes CGI, d'autres directives RewriteRule, ou des
+directives CustomLog.</p>
+
+<p>L'exemple suivant définit une variable d'environnement nommée 'image'
+avec une valeur de '1' si l'URI de la requête correspond à un fichier
+image. Cette variable d'environnement est ensuite utilisée pour exclure
+une telle requête du journal des accès.</p>
+
+<div class="example"><p><code>
+RewriteRule \.(png|gif|jpg) - [E=image:1]<br />
+CustomLog logs/access_log combined env=!image
+</code></p></div>
+
+<p>Notez que le même effet peut être obtenu à l'aide de la directive
+<code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code>. Cette technique
+est présentée à titre d'exemple et non de recommandation.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_f" id="flag_f">F|forbidden</a></h2>
+<p>L'utilisation du drapeau [F] permet de faire envoyer par le serveur au
+client un code de statut "403 Forbidden". Le même effet peut être obtenu à
+l'aide de la directive <code class="directive"><a href="../mod/mod_access.html#deny">Deny</a></code>,
+mais ce drapeau offre plus de souplesse dans l'attribution d'un statut
+Forbidden.</p>
+
+<p>La règle suivante va interdire la téléchargement de fichiers
+<code>.exe</code> depuis votre serveur.</p>
+
+<div class="example"><p><code>
+RewriteRule \.exe - [F]
+</code></p></div>
+
+<p>Cet exemple utilise la syntaxe "-" pour la cible de réécriture, ce
+qui signifie que l'URI de la requête n'est pas modifié. Il n'y a aucune
+raison de réécrire un URI, si vous avez l'intention d'interdire la
+requête.</p>
+
+<p>Lorsqu'on utilise [F], [L] est implicite - c'est à dire que la
+réponse est renvoyée immédiatement, et aucune autre règle n'est évaluée.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_g" id="flag_g">G|gone</a></h2>
+<p>Le drapeau [G] permet de faire envoyer par le serveur un code de statut
+"410 Gone" avec la réponse. Ce code indique qu'une ressource qui était
+disponible auparavant ne l'est plus actuellement.</p>
+
+<p>Comme dans le cas du drapeau [F], on utilise en général la syntaxe
+"-" pour la cible de réécriture lorsqu'on utilise le drapeau [G] :</p>
+
+<div class="example"><p><code>
+RewriteRule ancienne-ressource - [G,NC]
+</code></p></div>
+
+<p>Lorsqu'on utilise [F], [L] est implicite - c'est à dire que la
+réponse est renvoyée immédiatement, et aucune autre règle n'est évaluée.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_h" id="flag_h">H|handler</a></h2>
+<p>Force le traitement de la requête résultante par le gestionnaire
+spécifié. Par exemple, on peut utiliser ce drapeau pour forcer
+l'interprétation de tous les fichiers sans extension par le gestionnaire
+php :</p>
+
+<div class="example"><p><code>
+RewriteRule !\. - [H=application/x-httpd-php]
+</code></p></div>
+
+<p>
+L'expression rationnelle ci-dessus - <code>!\.</code> - correspond à
+toute requête qui ne contient pas le caractère <code>.</code>.
+</p>
+<p>On peut aussi utiliser ce drapeau pour forcer l'utilisation d'un
+certain gestionnaire en fonction de certaines conditions. Par exemple,
+l'extrait suivant utilisé dans un contexte de niveau serveur permet de
+faire en sorte que les fichiers <code>.php</code> soient
+<em>affichés</em> par <code>mod_php</code> dans le cas où ils font
+l'objet d'une requête avec l'extension <code>.phps</code> :</p>
+
+<div class="example"><p><code>
+RewriteRule ^(/source/.+\.php)s$ $1 [H=application/x-httpd-php-source]
+</code></p></div>
+
+
+<p>L'expression rationnelle ci-dessus -
+<code>^(/source/.+\.php)s$</code> - va correspondre à toute requête qui
+débutera par <code>/source/</code>, continuera par 1 ou n caractères
+puis par <code>.phps</code>. La référence arrière $1 fait référence à la
+correspondance capturée entre parenthèses de l'expression
+rationnelle.</p>
+
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_l" id="flag_l">L|last</a></h2>
+<p>Lorsque le drapeau [L] est présent, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+arrête le traitement du jeu de règles. Cela signifie dans la plupart des
+situations que si la règle s'applique, aucune autre règle ne sera
+traitée. Ce drapeau correspond à la commande Perl <code>last</code>, ou
+à la commande <code>break</code> en C. Utilisez ce drapeau pour indiquer
+que la règle courante doit être appliquée immédiatement, sans tenir
+compte des règles ultérieures.</p>
+
+<p>Si vous utilisez des règles <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> dans des fichiers
+<code>.htaccess</code> ou des sections <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>, il est important d'avoir quelques
+notions sur la manière dont les règles sont traitées. Pour simplifier,
+une fois les règles traitées, la requête réécrite est passée à nouveau
+au moteur d'interprétation des URLs afin que ce dernier puisse la
+traiter. Il est possible qu'au cours du traitement de la requête
+réécrite, le fichier <code>.htaccess</code> ou la section <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> soient à nouveau
+rencontrés, entraînant un nouveau traitement du jeu de règles depuis le
+début. Cette situation se présente le plus souvent lorsqu'une des règles
+provoque une redirection - interne ou externe - ce qui réinitialise le
+traitement de la requête.</p>
+
+<p>Si vous utilisez des directives <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> dans un de ces contextes,
+il importe par conséquent de prévoir explicitement des étapes permettant
+d'éviter un bouclage infini sur les règles,
+et de ne pas compter seulement sur
+le drapeau [L] pour terminer l'exécution d'une série de règles, comme
+décrit ci-dessous.</p>
+
+<p>Un autre drapeau, [END], permet non seulement d'interrompre le cycle
+courant du processus de réécriture, mais aussi d'empêcher toute
+réécriture ultérieure dans le contexte de répertoire (htaccess). Ceci ne
+s'applique pas aux nouvelles requêtes résultant de redirections
+externes.</p>
+
+<p>Dans l'exemple donné ici, toute requête est réécrite en
+<code>index.php</code>, la requête originale étant ajoutée comme chaîne
+de requête en argument à <code>index.php</code> ; cependant, la
+directive <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> permet de s'assurer que si
+la requête concerne déjà <code>index.php</code>, la directive <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> sera sautée.</p>
+
+<div class="example"><p><code>
+RewriteBase /<br />
+RewriteCond %{REQUEST_URI} !=/index.php<br />
+RewriteRule ^(.*) /index.php?req=$1 [L,PT]
+</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="flag_n" id="flag_n">N|next</a></h2>
+<p>Le drapeau [N] provoque un redémarrage du traitement des règles
+depuis le début, en utilisant le résultat du jeu de règles, sous
+réserve qu'il existe un point de démarrage ; à utiliser avec précautions
+car il peut provoquer un bouclage infini.
+</p>
+<p>
+Le drapeau [Next] peut servir, par exemple,
+à remplacer de manière répétitive
+une chaîne de caractère ou une lettre dans une requête. Dans l'exemple
+suivant, chaque occurence de A sera remplacée par B dans la requête, et
+ceci jusqu'il n'y ait plus de A à remplacer.
+</p>
+
+<div class="example"><p><code>
+RewriteRule (.*)A(.*) $1B$2 [N]
+</code></p></div>
+
+<p>Vous pouvez vous représenter ce traitement comme une boucle
+<code>while</code> : tant que le modèle de la règle correspond (c'est à
+dire, tant que l'URI contient un <code>A</code>),
+effectuer la substitution (c'est à dire, remplacer le <code>A</code> par
+un <code>B</code>).</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_nc" id="flag_nc">NC|nocase</a></h2>
+<p>Avec le drapeau [NC], le modèle de la règle <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> est comparé à la requête de
+manière insensible à la casse. C'est à dire que cette comparaison
+s'effectue sans tenir compte des majuscules/minuscules dans l'URI
+comparé.</p>
+
+<p>Dans l'exemple suivant, toute requête pour un fichier image sera
+transmise par Apache à votre serveur d'images dédié. La correspondance est
+insensible à la casse, si bien que par exemple, <code>.jpg</code> aussi
+bien que <code>.JPG</code> seront acceptés.</p>
+
+<div class="example"><p><code>
+RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC]
+</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="flag_ne" id="flag_ne">NE|noescape</a></h2>
+<p>Par défaut, les caractères spéciaux, comme <code>&</code> et
+<code>?</code>, sont convertis en leur équivalent
+hexadécimal. Le drapeau [NE] permet d'éviter cette conversion.
+</p>
+
+<div class="example"><p><code>
+RewriteRule ^/ancre/(.+) /grosse-page.html#$1 [NE,R]
+</code></p></div>
+
+<p>
+Dans l'exemple ci-dessus, <code>/anchor/xyz</code> est réécrit en
+<code>/bigpage.html#xyz</code>. En l'absence du drapeau [NE], le #
+aurait été converti en son équivalent hexadécimal, <code>%23</code>, ce
+qui aurait provoqué un code d'erreur "404 Not Found".
+</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_ns" id="flag_ns">NS|nosubreq</a></h2>
+<p>Le drapeau [NS] empêche la règle de s'appliquer aux sous-requêtes.
+Par exemple, une page incluse au moyen d'une SSI (Server
+Side Include) est une sous-requête, et vous ne voudrez probablement pas que
+la réécriture s'applique à ces sous-requêtes. Ainsi, lorsque
+<code class="module"><a href="../mod/mod_dir.html">mod_dir</a></code> recherche des informations à propos des
+fichiers par défaut du répertoire (comme les fichiers
+<code>index.html</code>), il s'agit d'une sous-requête interne, et vous
+ne désirez en général pas que ces sous-requêtes soient réécrites. Cette
+réécriture
+n'est pas toujours utile pour les sous-requêtes, et peut même causer des
+erreurs si l'ensemble du jeu de règles est appliqué. L'utilisation de
+ce drapeau permet d'exclure les règles qui peuvent poser problème.</p>
+
+<p>Comment déterminer si vous devez utiliser cette règle ou non : si
+vous préfixez les URLs avec des scripts CGI, afin de forcer leur
+traitement par le script CGI, vous vous exposez à des problèmes (ou du
+moins à une surcharge significative) avec les sous-requêtes. Dans ces
+cas, vous devez utiliser ce drapeau.</p>
+
+<p>
+Les images, scripts java, ou fichiers css, chargés en tant que partie
+d'une page html, ne sont pas des sous-requêtes - le navigateur les
+appelle sous forme de requêtes HTTP à part entière.
+</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_p" id="flag_p">P|proxy</a></h2>
+<p>L'utilisation du drapeau [P] entraîne le traitement de la requête par
+le module <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, et ceci via une requête de
+mandataire. Par exemple, si vous voulez que toutes les requêtes d'images
+soient traitées par un serveur d'images annexe, vous pouvez utiliser
+une règle de ce style :</p>
+
+<div class="example"><p><code>
+RewriteRule (.*)\.(jpg|gif|png) http://images.example.com$1.$2 [P]
+</code></p></div>
+
+<p>L'utilisation du drapeau [P] provoque aussi l'effet du drapeau [L] -
+autrement dit, la requête est immédiatement envoyée au mandataire, et
+toute règle ultérieure sera ignorée.</p>
+
+<p>
+Vous devez vous assurer que la chaîne de substitution soit un URI valide
+(commençant typiquement par <code>http://</code><em>nom-serveur</em>)
+qui puisse être traitée par le module <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>. Dans
+le cas contraire, le module mandataire vous renverra une erreur.
+L'utilisation de ce drapeau implémente de manière plus puissante la
+directive <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code>, pour
+faire correspondre le contenu distant à l'espace de nommage du serveur
+local.</p>
+
+<p>Note: <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> doit être activé pour pouvoir
+utiliser ce drapeau.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_pt" id="flag_pt">PT|passthrough</a></h2>
+
+<p>
+Par défaut, la cible (ou chaîne de substitution) d'une règle
+RewriteRule est sensée être un chemin de fichier. Avec le drapeau [PT],
+par contre, elle est traitée comme un URI. Autrement dit, avec le
+drapeau [PT], le résultat de la règle <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> est passé à nouveau au
+système de mise en correspondance des URLs avec le système de fichiers,
+de façon à ce que les systèmes de mise en correspondance basés sur les
+chemins de fichiers, comme la directive <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>, <code class="directive"><a href="../mod/core.html#redirect">Redirect</a></code>, ou <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>, par exemple, puissent avoir une
+chance d'accomplir leur tâche.
+</p>
+
+<p>
+Si par exemple, vous avez un <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> pour /icons, et une règle <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> qui renvoie vers /icons,
+vous devez utiliser le drapeau [PT] pour être sûr que l'<code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> sera bien évalué.
+</p>
+
+<div class="example"><p><code>
+Alias /icons /usr/local/apache/icons<br />
+RewriteRule /pics/(.+)\.jpg /icons/$1.gif [PT]
+</code></p></div>
+
+<p>
+Dans l'exemple précédent, en l'absence du drapeau [PT], l'Alias aurait
+été ignoré, ce qui aurait provoqué une erreur 'File not found'.
+</p>
+
+<p>Avec le drapeau <code>PT</code>, le drapeau <code>L</code> est
+implicite : la réécriture s'arrêtera afin de transmettre la requête à la
+phase suivante du traitement.</p>
+
+<p>Notez que le drapeau <code>PT</code> est implicite dans des contextes
+de répertoire comme les sections <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> ou les fichiers
+<code>.htaccess</code>. Le seul moyen de contourner ceci consiste à
+réécrire vers <code>-</code>.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_qsa" id="flag_qsa">QSA|qsappend</a></h2>
+<p>
+Quand l'URI de remplacement contient une chaîne de requête, le
+comportement par défaut de la règle <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> est de supprimer la <code>
+query string</code> (il s'agit des paramètres éventuellement passés dans l'URL après le
+caractère <code>?</code>, usuellement pour les formulaires traités par la
+méthode HTTP <code>GET</code>) existante, et de la remplacer par celle nouvellement créée.
+Avec le drapeau [QSA], les chaînes de requête peuvent être combinées.
+</p>
+
+<p>Considérons la règle suivante :</p>
+
+<div class="example"><p><code>
+RewriteRule /pages/(.+) /page.php?page=$1 [QSA]
+</code></p></div>
+
+<p>Avec le drapeau [QSA], une requête pour
+<code>/pages/123?one=two</code> sera réécrite en
+<code>/page.php?page=123&one=two</code>. Sans le drapeau [QSA], la
+même requête sera réécrite en <code>/page.php?page=123</code> -
+autrement dit, la chaîne de requête (<code>query string</code>) existante sera supprimée.
+</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_qsd" id="flag_qsd">QSD|qsdiscard</a></h2>
+<p>
+Lorsque l'URI de la requête contient une chaîne de paramètres, et si
+l'URI cible n'en contient pas, le comportement par défaut de la
+directive <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> consiste à copier cette
+chaîne de paramètres dans l'URI cible. Avec le drapeau [QSD], la chaîne
+de paramètres est supprimée.
+</p>
+
+<p>Ce drapeau est disponible dans les versions 2.4.0 et supérieures.</p>
+
+<p>
+Lorsque les drapeaux [QSD] et [QSA] sont utilisés ensemble, c'est le
+drapeau [QSD] qui l'emporte.
+</p>
+
+<p>
+Si l'URI cible possède une chaîne de paramètres, le comportement par
+défaut sera respecté - c'est à dire que la chaîne de paramètres
+originale sera supprimée et remplacée par la chaîne de paramètres de
+l'URI cible.
+</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_r" id="flag_r">R|redirect</a></h2>
+<p>
+L'utilisation du drapeau [R] provoque l'envoi d'une redirection au
+navigateur. Si une URL pleinement qualifiée (FQDN - fully qualified domain name)
+ est spécifiée (c'est à dire incluant <code>http://nom-du-serveur/</code>),
+ une redirection sera effectuée vers cette adresse. Dans le cas contraire,
+ le protocole courant, le nom du serveur et le numéro de port seront
+ utilisés pour générer l'URL envoyée avec la redirection.
+</p>
+
+<p><em>Tout</em> code de statut de réponse HTTP valide peut être
+spécifié, en utilisant la syntaxe [R=305], le code de statut 302 étant
+utilisé par défaut si aucun code n'est spécifié. Le code de statut
+spécifié n'est pas nécessairement un code de statut de redirection (3xx).
+</p>
+
+<p>Si le code de statut est en dehors de la plage des codes de
+redirection (300-399), la chaîne de substitution est entièrement
+supprimée, et la réécriture s'arrête comme si le drapeau <code>L</code>
+était utilisé.</p>
+
+<p>En plus des codes de statut de réponse, vous pouvez spécifier les
+codes de redirection en utilisant leurs noms symboliques :
+<code>temp</code> (défaut), <code>permanent</code>, ou
+<code>seeother</code>.</p>
+
+<p>
+Vous utiliserez presque toujours [R] en conjonction avec [L] (c'est à
+dire [R,L]), car employé seul, le drapeau [R] préfixe l'URI avec
+<code>http://cet-hôte[:ce-port]</code>, mais passe ensuite cette adresse
+à la règle suivante, ce qui provoquera le plus souvent des
+avertissements 'Invalid URI in request'.
+</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_s" id="flag_s">S|skip</a></h2>
+<p>Le drapeau [S] sert à sauter des règles que vous ne voulez pas voir
+exécuter. Ceci peut s'interpréter comme une instruction
+<code>goto</code> dans votre jeu de règles de réécriture. Dans
+l'exemple suivant, nous ne voulons exécuter la règle <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> que si l'URI demandé ne
+correspond pas à un fichier existant.</p>
+
+<div class="example"><p><code>
+# La requête concerne-t-elle un fichier qui n'existe pas ?<br />
+RewriteCond %{REQUEST_FILENAME} !-f<br />
+RewriteCond %{REQUEST_FILENAME} !-d<br />
+# Si c'est la cas, on saute les deux règles de réécriture suivantes<br />
+RewriteRule .? - [S=2]<br />
+<br />
+RewriteRule (.*\.gif) images.php?$1<br />
+RewriteRule (.*\.html) docs.php?$1
+</code></p></div>
+
+<p>Cette technique trouve son utilité dans le fait qu'une directive
+<code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> ne s'applique
+qu'à la règle qui la suit immédiatement. Ainsi, si vous voulez
+qu'une directive <code>RewriteCond</code> s'applique à plusieurs règles
+<code>RewriteRule</code>, une technique possible consiste à inverser ces
+conditions et à utiliser le drapeau [Skip]. Cette technique permet
+d'élaborer des pseudo-constructions if-then-else : la dernière règle du
+bloc then contiendra <code>skip=N</code>, où N est le nombre de règles
+contenues dans le bloc else.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flag_t" id="flag_t">T|type</a></h2>
+<p>Définit le type MIME de la réponse résultante renvoyée. L'effet est
+identique à celui de la directive <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code>.</p>
+
+<p>Par exemple, vous pouvez utiliser la technique suivante pour servir
+du code source Perl en tant que plein texte, s'il est requis d'une
+certaine manière :</p>
+
+<div class="example"><p><code>
+# Sert les fichier .pl en tant que plein texte<br />
+RewriteRule \.pl$ - [T=text/plain]
+</code></p></div>
+
+<p>Ou encore, si vous possédez une caméra qui produit des fichiers
+images jpeg sans extension, vous pouvez forcer le renvoi de ces images
+avec le type MIME correct en se basant sur le nom du fichier :</p>
+
+<div class="example"><p><code>
+# Les fichiers dont le nom contient 'IMG' sont des images jpg.<br />
+RewriteRule IMG - [T=image/jpg]
+</code></p></div>
+
+<p>Notez cependant qu'il s'agit d'un exemple trivial, et que le problème
+aurait pu être résolu en utilisant à la place la directive <code class="directive"><a href="../mod/core.html#filesmatch"><FilesMatch></a></code>. Il faut toujours
+envisager la possibilité d'une solution alternative à un problème avant
+d'avoir recours à la réécriture, qui sera toujours moins efficace qu'une
+solution alternative.</p>
+
+<p>
+Dans un contexte de niveau répertoire, n'utilisez que <code>-</code>
+(tiret) comme substitution, <em>dans toute la séquence de réécriture de
+mod_rewrite</em>, sinon le type MIME défini avec ce drapeau
+sera perdu suite à un retraitement interne (y compris les séquences de
+réécriture suivantes de mod_rewrite). Dans ce contexte, vous pouvez
+utiliser le drapeau <code>L</code> pour terminer la séquence
+<em>courante</em> de réécriture de mod_rewrite.</p>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Langues Disponibles: </span><a href="../en/rewrite/flags.html" hreflang="en" rel="alternate" title="English"> en </a> |
+<a href="../fr/rewrite/flags.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
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<!-- $LastChangedRevision$ -->
+<!-- $LastChangedRevision: 1078897 $ -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
limitations under the License.
-->
-<manualpage metafile="rewrite_flags.xml.meta">
+<manualpage metafile="flags.xml.meta">
<parentdocument href="./">Rewrite</parentdocument>
- <title>Apache mod_rewrite Flags</title>
+ <title>RewriteRule Flags</title>
<summary>
<p>This document discusses the flags which are available to the
<directive module="mod_rewrite">RewriteRule</directive> directive,
-providing detailed explanations and examples. This is not necessarily
-a comprehensive list of all flags available, so be sure to also
-consult the reference documentation.</p>
+providing detailed explanations and examples.</p>
</summary>
<seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
-<seealso><a href="rewrite_tech.html">Technical details</a></seealso>
-<seealso><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></seealso>
-<seealso><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide -
-advanced useful examples</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="introduction"><title>Introduction</title>
-<p><directive module="mod_rewrite">RewriteRule</directive>s can have
-their behavior modified by one or more flags. Flags are included in
+<p>A <directive module="mod_rewrite">RewriteRule</directive> can have
+its behavior modified by one or more flags. Flags are included in
square brackets at the end of the rule, and multiple flags are separated
by commas.</p>
<example>
a longer form, such as <code>cookie</code>. Some flags take one or more
arguments. Flags are not case sensitive.</p>
-</section>
-
-<section id="flags"><title>The flags</title>
-
-<p>Each flag has a long and short form. While it is most common to use
+<p>Each flag (with a few exceptions)
+has a long and short form. While it is most common to use
the short form, it is recommended that you familiarize yourself with the
long form, so that you remember what each flag is supposed to do.</p>
+<p>Flags that alter metadata associated with the request (T=, H=, E=)
+have no affect in per-directory and htaccess context, when a substitution
+(other than '-') is performed during the same round of rewrite processing.
+</p>
+
<p>Presented here are each of the available flags, along with an example
of how you might use them.</p>
+</section>
+
+<section id="flag_b"><title>B (escape backreferences)</title>
+<p>The [B] flag instructs <directive
+module="mod_rewrite">RewriteRule</directive> to escape non-alphanumeric
+characters before applying the transformation.
+</p>
+
+<p><code>mod_rewrite</code> has to unescape URLs before mapping them,
+so backreferences will be unescaped at the time they are applied.
+Using the B flag, non-alphanumeric characters in backreferences
+will be escaped. For example, consider the rule:</p>
+
+<example>
+RewriteRule ^(/.*)$ /index.php?show=$1
+</example>
+
+<p>This will map <code>/C++</code> to
+<code>/index.php?show=/C++</code>. But it will also map
+<code>/C%2b%2b</code> to <code>/index.php?show=/C++</code>, because
+the <code>%2b</code> has been unescaped. With the B flag, it will
+instead map to <code>/index.php?show=/C%2b%2b</code>.</p>
+
+<p>This escaping is particularly necessary in a proxy situation,
+when the backend may break if presented with an unescaped URL.</p>
+
+</section>
<section id="flag_c"><title>C|chain</title>
<p>The [C] or [chain] flag indicates that the <directive
<section id="flag_co"><title>CO|cookie</title>
<p>The [CO], or [cookie] flag, allows you to set a cookie when a
particular <directive module="mod_rewrite">RewriteRule</directive>
-matches. The argument consists of three required fields and two optional
+matches. The argument consists of three required fields and five optional
fields.</p>
-<p>You must declare a name and value for the cookie to be set, and the
-domain for which you wish the cookie to be valid. You may optionally set
-the lifetime of the cookie, and the path for which it should be
-returned.</p>
-<p>By default, the lifetime of the cookie is the current browser
-session.</p>
-<p>By default, the path for which the cookie will be valid is "/" - that
-is, the entire website.</p>
+
+<p>The full syntax for the flag, including all attributes, is as
+follows:</p>
+
+<example>
+[CO=NAME:VALUE:domain:lifetime:path:secure:httponly]
+</example>
+
+<p>You must declare a name and value for the cookie to be set.</p>
+
+<p>You may optionally also set the following values:</p>
+
+<dl>
+<dt>Domain</dt>
+<dd>The domain for which you want the cookie to be valid. This may be a
+hostname, such as <code>www.example.com</code>, or it may be a domain,
+such as <code>.example.com</code>. It must be at least two parts
+separated by a dot. That is, it may not be merely <code>.com</code> or
+<code>.net</code>. Cookies of that kind are forbidden by the cookie
+security model.</dd>
+<dd>The default value for the domain is the current domain.</dd>
+
+<dt>Lifetime</dt>
+<dd>The time for which the cookie will persist, in minutes.</dd>
+<dd>A value of 0 indicates that the cookie will persist only for the
+current browser session. This is the default value if none is
+specified.</dd>
+
+<dt>Path</dt>
+<dd>The path, on the current website, for which the cookie is valid,
+such as <code>/customers/</code> or <code>/files/download/</code>.</dd>
+<dd>By default, this is set to <code>/</code> - that is, the entire
+website.</dd>
+
+<dt>Secure</dt>
+<dd>If set to <code>secure</code>, <code>true</code>, or <code>1</code>,
+the cookie will only be permitted to be translated via secure (https)
+connections.</dd>
+
+<dt>httponly</dt>
+<dd>If set to <code>HttpOnly</code>, <code>true</code>, or
+<code>1</code>, the cookie will have the <code>HttpOnly</code> flag set,
+which means that the cookie will be inaccessible to JavaScript code on
+browsers that support this feature.</dd>
+</dl>
+
<p>Several examples are offered here:</p>
<example>
RewriteEngine On<br />
-RewriteRule ^/index.html - [CO=frontdoor:yes:.apache.org:1440:/]
+RewriteRule ^/index\.html - [CO=frontdoor:yes:.example.com:1440:/]
</example>
-<p>This rule doesn't rewrite the request (the "-" rewrite target tells
-mod_rewrite to pass the request through unchanged) but sets a cookie
+<p>In the example give, the rule doesn't rewrite the request.
+The "-" rewrite target tells mod_rewrite to pass the request
+through unchanged. Instead, it sets a cookie
called 'frontdoor' to a value of 'yes'. The cookie is valid for any host
-in the <code>.apache.org</code> domain. It will be set to expire in 1440
+in the <code>.example.com</code> domain. It will be set to expire in 1440
minutes (24 hours) and will be returned for all URIs.</p>
</section>
+<section id="flag_dpi"><title>DPI|discardpathinfo</title>
+<p>The DPI flag causes the PATH_INFO portion of the rewritten URI to be
+discarded.</p>
+<p>This flag is available in version 2.2.12 and later.</p>
+<p>In per-directory context, the URI each <directive>RewriteRule</directive>
+compares against is the concatenation of the current values of the URI
+and PATH_INFO.</p>
+
+<p>The current URI can be the initial URI as requested by the client, the
+result of a previous round of mod_rewrite processing, or the result of
+a prior rule in the current round of mod_rewrite processing.</p>
+
+<p>In contrast, the PATH_INFO that is appended to the URI before each
+rule reflects only the value of PATH_INFO before this round of
+mod_rewrite processing. As a consequence, if large portions
+of the URI are matched and copied into a substitution in multiple
+<directive>RewriteRule</directive> directives, without regard for
+which parts of the URI came from the current PATH_INFO, the final
+URI may have multiple copies of PATH_INFO appended to it.</p>
+
+<p>Use this flag on any substitution where the PATH_INFO that resulted
+from the previous mapping of this request to the filesystem is not of
+interest. This flag permanently forgets the PATH_INFO established
+before this round of mod_rewrite processing began. PATH_INFO will
+not be recalculated until the current round of mod_rewrite processing
+completes. Subsequent rules during this round of processing will see
+only the direct result of substitutions, without any PATH_INFO
+appended.</p>
+</section>
+
<section id="flag_e"><title>E|env</title>
<p>With the [E], or [env] flag, you can set the value of an environment
variable. Note that some environment variables may be set after the rule
</section>
<section id="flag_f"><title>F|forbidden</title>
-<p>Using the [F] flag causes Apache to return a 403 Forbidden status
+<p>Using the [F] flag causes the server to return a 403 Forbidden status
code to the client. While the same behavior can be accomplished using
the <directive module="mod_access">Deny</directive> directive, this
allows more flexibility in assigning a Forbidden status.</p>
that the requested URI is not modified. There's no reason to rewrite to
another URI, if you're going to forbid the request.</p>
+<p>When using [F], an [L] is implied - that is, the response is returned
+immediately, and no further rules are evaluated.</p>
+
</section>
<section id="flag_g"><title>G|gone</title>
-<p>The [G] flag forces Apache to return a 410 Gone status with the
+<p>The [G] flag forces the server to return a 410 Gone status with the
response. This indicates that a resource used to be available, but is no
longer available.</p>
<example>
RewriteRule oldproduct - [G,NC]
</example>
+
+<p>When using [F], an [L] is implied - that is, the response is returned
+immediately, and no further rules are evaluated.</p>
+
</section>
<section id="flag_h"><title>H|handler</title>
The regular expression above - <code>!\.</code> - will match any request
that does not contain the literal <code>.</code> character.
</p>
+
+<p>This can be also used to force the handler based on some conditions.
+For example, the following snippet used in per-server context allows
+<code>.php</code> files to be <em>displayed</em> by <code>mod_php</code>
+if they are requested with the <code>.phps</code> extension:</p>
+
+<example>
+RewriteRule ^(/source/.+\.php)s$ $1 [H=application/x-httpd-php-source]
+</example>
+
+<p>The regular expression above - <code>^(/source/.+\.php)s$</code> - will
+match any request that starts with <code>/source/</code> followed by 1 or
+n characters followed by <code>.phps</code> literally. The backreference
+$1 referrers to the captured match within parenthesis of the regular
+expression.</p>
</section>
<section id="flag_l"><title>L|last</title>
<p>The [L] flag causes <module>mod_rewrite</module> to stop processing
the rule set. In most contexts, this means that if the rule matches, no
-further rules will be processed.</p>
+further rules will be processed. This corresponds to the
+<code>last</code> command in Perl, or the <code>break</code> command in
+C. Use this flag to indicate that the current rule should be applied
+immediately without considering further rules.</p>
<p>If you are using <directive
module="mod_rewrite">RewriteRule</directive> in either
<p>It is therefore important, if you are using <directive
module="mod_rewrite">RewriteRule</directive> directives in one of these
-context that you take explicit steps to avoid rules looping, and not
+contexts, that you take explicit steps to avoid rules looping, and not
count solely on the [L] flag to terminate execution of a series of
rules, as shown below.</p>
+<p> An alternative flag, [END], can be used to terminate not only the
+current round of rewrite processing but prevent any subsequent
+rewrite processing from occuring in per-directory (htaccess)
+context. This does not apply to new requests resulting from external
+redirects.</p>
+
<p>The example given here will rewrite any request to
<code>index.php</code>, giving the original request as a query string
-argument to <code>index.php</code>, however, if the request is already
-for <code>index.php</code>, this rule will be skipped.</p>
+argument to <code>index.php</code>, however, the <directive
+module="mod_rewrite">RewriteCond</directive> ensures that if the request
+is already for <code>index.php</code>, the <directive
+module="mod_rewrite">RewriteRule</directive> will be skipped.</p>
<example>
-RewriteCond %{REQUEST_URI} !index\.php<br />
-RewriteRule ^(.*) index.php?req=$1 [L]
+RewriteBase /<br />
+RewriteCond %{REQUEST_URI} !=/index.php<br />
+RewriteRule ^(.*) /index.php?req=$1 [L,PT]
</example>
</section>
<section id="flag_n"><title>N|next</title>
<p>
-The [N] flag causes the ruleset to start over again from the top. Use
+The [N] flag causes the ruleset to start over again from the top, using
+the result of the ruleset so far as a starting point. Use
with extreme caution, as it may result in loop.
</p>
<p>
</example>
<p>You can think of this as a <code>while</code> loop: While this
-pattern still matches, perform this substitution.</p>
+pattern still matches (i.e., while the URI still contains an
+<code>A</code>), perform this substitution (i.e., replace the
+<code>A</code> with a <code>B</code>).</p>
</section>
<p>Use of the [NS] flag prevents the rule from being used on
subrequests. For example, a page which is included using an SSI (Server
Side Include) is a subrequest, and you may want to avoid rewrites
-happening on those subrequests.</p>
+happening on those subrequests. Also, when <module>mod_dir</module>
+tries to find out information about possible directory default files
+(such as <code>index.html</code> files), this is an internal
+subrequest, and you often want to avoid rewrites on such subrequests.
+On subrequests, it is not always useful, and can even cause errors, if
+the complete set of rules are applied. Use this flag to exclude
+problematic rules.</p>
+
+<p>To decide whether or not to use this rule: if you prefix URLs with
+CGI-scripts, to force them to be processed by the CGI-script, it's
+likely that you will run into problems (or significant overhead)
+on sub-requests. In these cases, use this flag.</p>
<p>
Images, javascript files, or css files, loaded as part of an HTML page,
RewriteRule (.*)\.(jpg|gif|png) http://images.example.com$1.$2 [P]
</example>
-<p>Use of the [P] flag implies [L] - that is, the request is immediatly
+<p>Use of the [P] flag implies [L] - that is, the request is immediately
pushed through the proxy, and any following rules will not be
considered.</p>
+<p>
+You must make sure that the substitution string is a valid URI
+(typically starting with <code>http://</code><em>hostname</em>) which can be
+handled by the <module>mod_proxy</module>. If not, you will get an
+error from the proxy module. Use this flag to achieve a
+more powerful implementation of the <directive
+module="mod_proxy">ProxyPass</directive> directive,
+to map remote content into the namespace of the local server.</p>
+
+<p>Note: <module>mod_proxy</module> must be enabled in order
+to use this flag.</p>
+
</section>
<section id="flag_pt"><title>PT|passthrough</title>
use of the [PT] flag causes the result of the <directive
module="mod_rewrite">RewriteRule</directive> to be passed back through
URL mapping, so that location-based mappings, such as <directive
-module="mod_alias">Alias</directive>, for example, might have a chance to take
-effect.
+module="mod_alias">Alias</directive>, <directive
+module="core">Redirect</directive>, or <directive
+module="mod_alias">ScriptAlias</directive>, for example, might have a
+chance to take effect.
</p>
<p>
ignored, resulting in a 'File not found' error being returned.
</p>
+<p>The <code>PT</code> flag implies the <code>L</code> flag:
+rewriting will be stopped in order to pass the request to
+the next phase of processing.</p>
+
+<p>Note that the <code>PT</code> flag is implied in per-directory
+contexts such as
+<directive type="section" module="core">Directory</directive> sections
+or in <code>.htaccess</code> files. The only way to circumvent that
+is to rewrite to <code>-</code>.</p>
+
</section>
<section id="flag_qsa"><title>QSA|qsappend</title>
Use of the [R] flag causes a HTTP redirect to be issued to the browser.
If a fully-qualified URL is specified (that is, including
<code>http://servername/</code>) then a redirect will be issued to that
-location. Otherwise, the current servername will be used to generate the
-URL sent with the redirect.
+location. Otherwise, the current protocol, servername, and port number
+will be used to generate the URL sent with the redirect.
</p>
<p>
-A status code may be specified, in the range 300-399, with a 302 status
-code being used by default if none is specified.
+<em>Any</em> valid HTTP response status code may be specified,
+using the syntax [R=305], with a 302 status code being used by
+default if none is specified. The status code specified need not
+necessarily be a redirect (3xx) status code.
</p>
+<p>If a status code is outside the redirect range (300-399) then the
+substitution string is dropped entirely, and rewriting is stopped as if
+the <code>L</code> were used.</p>
+
+<p>In addition to response status codes, you may also specify redirect
+status using their symbolic names: <code>temp</code> (default),
+<code>permanent</code>, or <code>seeother</code>.</p>
+
<p>
You will almost always want to use [R] in conjunction with [L] (that is,
use [R,L]) because on its own, the [R] flag prepends
<directive module="mod_rewrite">RewriteRule</directive> immediately
following it. Thus, if you want to make a <code>RewriteCond</code> apply
to several <code>RewriteRule</code>s, one possible technique is to
-negate those conditions and use a [Skip] flag.</p>
-
+negate those conditions and use a [Skip] flag. So, you can
+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.</p>
</section>
<section id="flag_t"><title>T|type</title>
<p>
If used in per-directory context, use only <code>-</code> (dash)
-as the substitution <em>for the entire round of mod_rewrite processing</em>,
-otherwise the MIME-type set with this flag is lost due to an internal
+as the substitution <em>for the entire round of mod_rewrite processing</em>,
+otherwise the MIME-type set with this flag is lost due to an internal
re-processing (including subsequent rounds of mod_rewrite processing).
-The <code>L</code> flag can be useful in this context to end the
+The <code>L</code> flag can be useful in this context to end the
<em>current</em> round of mod_rewrite processing.</p>
+
</section>
-</section>
+
</manualpage>
--- /dev/null
+<?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 : 1078897 -->
+<!-- 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="flags.xml.meta">
+<parentdocument href="./">Rewrite</parentdocument>
+
+ <title>Les drapeaux de réécriture</title>
+
+<summary>
+<p>Ce document décrit les drapeaux disponibles dans la directive
+<directive module="mod_rewrite">RewriteRule</directive>, en fournissant
+des explications détaillées et des exemples.</p>
+</summary>
+
+<seealso><a href="../mod/mod_rewrite.html">Documentation du module</a></seealso>
+<seealso><a href="intro.html">Introduction à mod_rewrite</a></seealso>
+<seealso><a href="remapping.html">Redirection and 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="introduction"><title>Introduction</title>
+<p>Le comportement d'une directive <directive
+module="mod_rewrite">RewriteRule</directive> peut être modifié par un ou
+plusieurs drapeaux. Les drapeaux sont situés en fin de règle, entourés
+de crochets, et séparés le cas échéant par des virgules.</p>
+<example>
+RewriteRule modèle cible [drapeau1,drapeau2,drapeau3]
+</example>
+
+<p>Les drapeaux ont tous une forme courte, comme <code>CO</code>, ainsi
+qu'une forme longue, comme <code>cookie</code>. Certains drapeaux
+peuvent avoir un ou plusieurs arguments. Les drapeaux sont insensibles à
+la casse.</p>
+
+<p>Chaque drapeau (à quelques exceptions près) possède une forme longue et une forme courte. Bien que
+la forme courte soit la plus couramment utilisée, nous vous recommandons
+de vous familiariser avec les drapeaux sous leur forme longue, afin de
+bien mémoriser ce que chaque drapeau est supposé faire.</p>
+
+<p>Les drapeaux qui modifient les métadonnées associées à la requête
+(T=, H=, E=) n'ont aucun effet dans un contexte de répertoire ou de
+fichier htaccess, lorsqu'une substitution (autre que '-') est effectuée
+au cours de la même passe du processus de réécriture.
+</p>
+
+<p>Chaque drapeau disponible est présenté ici, avec un exemple
+d'utilisation.</p>
+</section>
+
+<section id="flag_b"><title>B (échappement dans les références arrières)</title>
+<p>Avec le drapeau [B], la directive <directive
+module="mod_rewrite">RewriteRule</directive> échappe les caractères
+non-alphanumériques avant d'appliquer la transformation.</p>
+
+<p><code>mod_rewrite</code> doit supprimer les séquences d'échappement
+des URLs avant leur
+mise en correspondance avec le système de fichiers ; les séquences
+d'échappement sont donc supprimées des références arrières au moment où
+ces dernières sont appliquées. Avec le drapeau B, les caractères
+non-alphanumériques des références arrières seront échappés. Considérons
+par exemple cette règle :</p>
+
+<example>
+RewriteRule ^(/.*)$ /index.php?show=$1
+</example>
+
+<p>Avec cet exemple, <code>/C++</code> sera réécrit en
+<code>/index.php?show=/C++</code>. Mais <code>/C%2b%2b</code> sera lui
+aussi réécrit en <code>/index.php?show=/C++</code>, car le caractère
+<code>%2b</code> aura été "déséchappé". Avec le drapeau B par contre,
+<code>/C%2b%2b</code> sera réécrit en
+<code>/index.php?show=/C%2b%2b</code>.</p>
+
+<p>Ce processus d'échappement est en particulier nécessaire dans le
+contexte d'un mandataire, où l'accès au serveur d'arrière-plan échouera
+si on présente à ce dernier une URL non échappée.</p>
+
+</section>
+
+<section id="flag_c"><title>C|chain</title>
+<p>Le drapeau [C] ou [chain] indique que la règle <directive
+module="mod_rewrite">RewriteRule</directive> est chaînée avec la
+suivante. Autrement dit, si la règle s'applique, elle est traitée
+normalement et passe le contrôle à la règle suivante. Par contre, si
+elle ne s'applique pas, la règle suivante, ainsi que toutes les règles
+chaînées qui suivent, seront sautées.</p>
+
+</section>
+
+<section id="flag_co"><title>CO|cookie</title>
+<p>Le drapeau [CO], ou [cookie], vous permet de définir un cookie
+lorsqu'une règle <directive module="mod_rewrite">RewriteRule</directive>
+s'applique. Il possède trois arguments obligatoires et
+cinq arguments optionnels.</p>
+
+<p>La syntaxe complète de ce drapeau, avec tous ses attributs, est la
+suivante :</p>
+
+<example>
+[CO=NAME:VALUE:domain:lifetime:path:secure:httponly]
+</example>
+
+<p>Vous devez déclarer un nom et une valeur pour que le cookie puisse
+être défini.</p>
+
+<p>Vous pouvez aussi définir les valeurs suivantes :</p>
+
+<dl>
+<dt>Domain</dt>
+<dd>Le domaine pour lequel vous souhaitez que le cookie soit valide. Ce
+peut être un nom de serveur, comme <code>www.example.com</code>, ou un
+domaine, comme <code>.example.com</code>. Il doit comporter au moins
+deux parties séparées par un point. C'est à dire que vous ne pouvez pas
+utiliser les valeurs <code>.com</code> ou <code>.net</code>. En effet,
+ce style de cookie est interdit par le modèle de sécurité des cookies.</dd>
+<dd>La valeur par défaut est le domaine courant.</dd>
+
+<dt>Lifetime</dt>
+<dd>La durée de vie du cookie, en minutes.</dd>
+<dd>Une valeur de 0 indique une durée de vie correspondant à la session
+courante du navigateur. Il s'agit de la valeur par défaut.</dd>
+
+<dt>Path</dt>
+<dd>Le chemin, sur le site web concerné, pour lequel le cookie est
+valide, du style <code>/clients/</code> or
+<code>/fichiers/telechargement/</code>.</dd>
+<dd>La valeur par défaut est <code>/</code> - c'est à dire l'ensemble du
+site web.</dd>
+
+<dt>Secure</dt>
+<dd>Si cet argument a pour valeur <code>secure</code>,
+<code>true</code>, ou <code>1</code>, le cookie ne pourra être transmis
+que dans le cadre d'une connexion sécurisée (https).</dd>
+
+<dt>httponly</dt>
+<dd>Si cet argument a pour valeur <code>HttpOnly</code>,
+<code>true</code>, ou <code>1</code>, le cookie aura son drapeau
+<code>HttpOnly</code> activé, ce qui signifie qu'il sera inaccessible au
+code JavaScript pour les navigateurs qui supportent cette
+fonctionnalité.</dd>
+</dl>
+
+<p>Voici un exemple :</p>
+
+<example>
+RewriteEngine On<br />
+RewriteRule ^/index\.html - [CO=frontdoor:yes:.example.org:1440:/]
+</example>
+
+<p>Dans l'exemple ci-dessus, la règle ne réécrit
+pas la requête. La cible de réécriture "-"
+indique à mod_rewrite de transmettre la requête sans
+modification. Par contre, il
+définit un cookie nommé 'frontdoor' avec une valeur 'yes'. Le cookie est
+valide pour tout hôte situé dans le domaine <code>.example.org</code>. Sa
+durée de vie est limitée à 1440 minutes (24 heures), et il sera renvoyé
+pour tous les URIs.</p>
+
+</section>
+
+<section id="flag_dpi"><title>DPI|discardpathinfo</title>
+<p>Avec le drapeau DPI, la partie PATH_INFO de l'URI
+réécrit est supprimée.</p>
+<p>Ce drapeau est disponible dans les versions 2.2.12 et supérieures.</p>
+<p>Dans un contexte de répertoire, l'URI mis en comparaison par chaque
+règle <directive>RewriteRule</directive> est la concaténation des
+valeurs courantes de l'URI et de PATH_INFO.</p>
+
+<p>L'URI courant peut être l'URI initial tel qu'il a été fourni par le
+client, le résultat d'une passe précédente du processus de réécriture,
+ou le résultat de la règle précédente dans le processus courant de
+réécriture.</p>
+
+<p>Par contre, la partie PATH_INFO ajoutée à l'URI avant chaque règle ne
+reflète que la valeur de PATH_INFO avant la passe courante du processus
+de réécriture. En conséquence, si de larges portions de l'URI
+correspondent et sont traduites via plusieurs directives
+<directive>RewriteRule</directive>, sans prendre en compte
+quelles parties de l'URI provenaient du PATH_INFO courant, l'URI final
+pourra se voir ajouter plusieurs copies de PATH_INFO.</p>
+
+<p>Utilisez ce drapeau pour toute substitution où la présence du PATH_INFO qui
+résultait de la mise en correspondance précédente de cette requête avec
+le système de fichier n'est pas nécessaire. Avec ce drapeau, le
+PATH_INFO établi avant que cette passe du processus de réécriture ne
+débute est oublié. PATH_INFO ne sera pas recalculé tant que la passe
+courante du processus de réécriture ne sera pas achevée. Les règles
+suivantes de cette passe ne verront que le résultat direct des
+substitutions, sans aucun PATH_INFO ajouté.</p>
+</section>
+
+<section id="flag_e"><title>E|env</title>
+<p>Avec le drapeau [E], ou [env], vous pouvez définir la valeur d'une
+variable d'environnement. Notez que certaines variables d'environnement
+peuvent être définies après le traitement de la règle, annulant par
+la-même ce que vous avez défini. Voir le <a href="../env.html">document
+sur les variables d'environnement</a> pour plus de détails sur le
+fonctionnement des variables d'environnement.</p>
+
+<p>La syntaxe complète pour ce drapeau est :</p>
+
+<example>
+[E=!VAR]
+</example>
+
+<p><code>VAL</code> peut comporter des références arrières
+(<code>$N</code> ou <code>%N</code>) qui seront développées.</p>
+
+<p>En utilisant la version courte</p>
+
+<example>
+[E=VAR]
+</example>
+
+<p>vous pouvez définir la variable d'environnement nommée
+<code>VAR</code> avec une valeur vide.</p>
+
+<p>La forme</p>
+
+<example>
+[E=!VAR]
+</example>
+
+<p>permet d'annuler la définition de la variable <code>VAR</code>.</p>
+
+<p>Les variables d'environnement s'emploient dans différents contextes,
+comme les programmes CGI, d'autres directives RewriteRule, ou des
+directives CustomLog.</p>
+
+<p>L'exemple suivant définit une variable d'environnement nommée 'image'
+avec une valeur de '1' si l'URI de la requête correspond à un fichier
+image. Cette variable d'environnement est ensuite utilisée pour exclure
+une telle requête du journal des accès.</p>
+
+<example>
+RewriteRule \.(png|gif|jpg) - [E=image:1]<br />
+CustomLog logs/access_log combined env=!image
+</example>
+
+<p>Notez que le même effet peut être obtenu à l'aide de la directive
+<directive module="mod_setenvif">SetEnvIf</directive>. Cette technique
+est présentée à titre d'exemple et non de recommandation.</p>
+</section>
+
+<section id="flag_f"><title>F|forbidden</title>
+<p>L'utilisation du drapeau [F] permet de faire envoyer par le serveur au
+client un code de statut "403 Forbidden". Le même effet peut être obtenu à
+l'aide de la directive <directive module="mod_access">Deny</directive>,
+mais ce drapeau offre plus de souplesse dans l'attribution d'un statut
+Forbidden.</p>
+
+<p>La règle suivante va interdire la téléchargement de fichiers
+<code>.exe</code> depuis votre serveur.</p>
+
+<example>
+RewriteRule \.exe - [F]
+</example>
+
+<p>Cet exemple utilise la syntaxe "-" pour la cible de réécriture, ce
+qui signifie que l'URI de la requête n'est pas modifié. Il n'y a aucune
+raison de réécrire un URI, si vous avez l'intention d'interdire la
+requête.</p>
+
+<p>Lorsqu'on utilise [F], [L] est implicite - c'est à dire que la
+réponse est renvoyée immédiatement, et aucune autre règle n'est évaluée.</p>
+
+</section>
+
+<section id="flag_g"><title>G|gone</title>
+<p>Le drapeau [G] permet de faire envoyer par le serveur un code de statut
+"410 Gone" avec la réponse. Ce code indique qu'une ressource qui était
+disponible auparavant ne l'est plus actuellement.</p>
+
+<p>Comme dans le cas du drapeau [F], on utilise en général la syntaxe
+"-" pour la cible de réécriture lorsqu'on utilise le drapeau [G] :</p>
+
+<example>
+RewriteRule ancienne-ressource - [G,NC]
+</example>
+
+<p>Lorsqu'on utilise [F], [L] est implicite - c'est à dire que la
+réponse est renvoyée immédiatement, et aucune autre règle n'est évaluée.</p>
+
+</section>
+
+<section id="flag_h"><title>H|handler</title>
+<p>Force le traitement de la requête résultante par le gestionnaire
+spécifié. Par exemple, on peut utiliser ce drapeau pour forcer
+l'interprétation de tous les fichiers sans extension par le gestionnaire
+php :</p>
+
+<example>
+RewriteRule !\. - [H=application/x-httpd-php]
+</example>
+
+<p>
+L'expression rationnelle ci-dessus - <code>!\.</code> - correspond à
+toute requête qui ne contient pas le caractère <code>.</code>.
+</p>
+<p>On peut aussi utiliser ce drapeau pour forcer l'utilisation d'un
+certain gestionnaire en fonction de certaines conditions. Par exemple,
+l'extrait suivant utilisé dans un contexte de niveau serveur permet de
+faire en sorte que les fichiers <code>.php</code> soient
+<em>affichés</em> par <code>mod_php</code> dans le cas où ils font
+l'objet d'une requête avec l'extension <code>.phps</code> :</p>
+
+<example>
+RewriteRule ^(/source/.+\.php)s$ $1 [H=application/x-httpd-php-source]
+</example>
+
+
+<p>L'expression rationnelle ci-dessus -
+<code>^(/source/.+\.php)s$</code> - va correspondre à toute requête qui
+débutera par <code>/source/</code>, continuera par 1 ou n caractères
+puis par <code>.phps</code>. La référence arrière $1 fait référence à la
+correspondance capturée entre parenthèses de l'expression
+rationnelle.</p>
+
+
+</section>
+
+<section id="flag_l"><title>L|last</title>
+<p>Lorsque le drapeau [L] est présent, <module>mod_rewrite</module>
+arrête le traitement du jeu de règles. Cela signifie dans la plupart des
+situations que si la règle s'applique, aucune autre règle ne sera
+traitée. Ce drapeau correspond à la commande Perl <code>last</code>, ou
+à la commande <code>break</code> en C. Utilisez ce drapeau pour indiquer
+que la règle courante doit être appliquée immédiatement, sans tenir
+compte des règles ultérieures.</p>
+
+<p>Si vous utilisez des règles <directive
+module="mod_rewrite">RewriteRule</directive> dans des fichiers
+<code>.htaccess</code> ou des sections <directive type="section"
+module="core">Directory</directive>, il est important d'avoir quelques
+notions sur la manière dont les règles sont traitées. Pour simplifier,
+une fois les règles traitées, la requête réécrite est passée à nouveau
+au moteur d'interprétation des URLs afin que ce dernier puisse la
+traiter. Il est possible qu'au cours du traitement de la requête
+réécrite, le fichier <code>.htaccess</code> ou la section <directive
+type="section" module="core">Directory</directive> soient à nouveau
+rencontrés, entraînant un nouveau traitement du jeu de règles depuis le
+début. Cette situation se présente le plus souvent lorsqu'une des règles
+provoque une redirection - interne ou externe - ce qui réinitialise le
+traitement de la requête.</p>
+
+<p>Si vous utilisez des directives <directive
+module="mod_rewrite">RewriteRule</directive> dans un de ces contextes,
+il importe par conséquent de prévoir explicitement des étapes permettant
+d'éviter un bouclage infini sur les règles,
+et de ne pas compter seulement sur
+le drapeau [L] pour terminer l'exécution d'une série de règles, comme
+décrit ci-dessous.</p>
+
+<p>Un autre drapeau, [END], permet non seulement d'interrompre le cycle
+courant du processus de réécriture, mais aussi d'empêcher toute
+réécriture ultérieure dans le contexte de répertoire (htaccess). Ceci ne
+s'applique pas aux nouvelles requêtes résultant de redirections
+externes.</p>
+
+<p>Dans l'exemple donné ici, toute requête est réécrite en
+<code>index.php</code>, la requête originale étant ajoutée comme chaîne
+de requête en argument à <code>index.php</code> ; cependant, la
+directive <directive
+module="mod_rewrite">RewriteCond</directive> permet de s'assurer que si
+la requête concerne déjà <code>index.php</code>, la directive <directive
+module="mod_rewrite">RewriteRule</directive> sera sautée.</p>
+
+<example>
+RewriteBase /<br />
+RewriteCond %{REQUEST_URI} !=/index.php<br />
+RewriteRule ^(.*) /index.php?req=$1 [L,PT]
+</example>
+</section>
+
+<section id="flag_n"><title>N|next</title>
+<p>Le drapeau [N] provoque un redémarrage du traitement des règles
+depuis le début, en utilisant le résultat du jeu de règles, sous
+réserve qu'il existe un point de démarrage ; à utiliser avec précautions
+car il peut provoquer un bouclage infini.
+</p>
+<p>
+Le drapeau [Next] peut servir, par exemple,
+à remplacer de manière répétitive
+une chaîne de caractère ou une lettre dans une requête. Dans l'exemple
+suivant, chaque occurence de A sera remplacée par B dans la requête, et
+ceci jusqu'il n'y ait plus de A à remplacer.
+</p>
+
+<example>
+RewriteRule (.*)A(.*) $1B$2 [N]
+</example>
+
+<p>Vous pouvez vous représenter ce traitement comme une boucle
+<code>while</code> : tant que le modèle de la règle correspond (c'est à
+dire, tant que l'URI contient un <code>A</code>),
+effectuer la substitution (c'est à dire, remplacer le <code>A</code> par
+un <code>B</code>).</p>
+
+</section>
+
+<section id="flag_nc"><title>NC|nocase</title>
+<p>Avec le drapeau [NC], le modèle de la règle <directive
+module="mod_rewrite">RewriteRule</directive> est comparé à la requête de
+manière insensible à la casse. C'est à dire que cette comparaison
+s'effectue sans tenir compte des majuscules/minuscules dans l'URI
+comparé.</p>
+
+<p>Dans l'exemple suivant, toute requête pour un fichier image sera
+transmise par Apache à votre serveur d'images dédié. La correspondance est
+insensible à la casse, si bien que par exemple, <code>.jpg</code> aussi
+bien que <code>.JPG</code> seront acceptés.</p>
+
+<example>
+RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC]
+</example>
+</section>
+
+<section id="flag_ne"><title>NE|noescape</title>
+<p>Par défaut, les caractères spéciaux, comme <code>&</code> et
+<code>?</code>, sont convertis en leur équivalent
+hexadécimal. Le drapeau [NE] permet d'éviter cette conversion.
+</p>
+
+<example>
+RewriteRule ^/ancre/(.+) /grosse-page.html#$1 [NE,R]
+</example>
+
+<p>
+Dans l'exemple ci-dessus, <code>/anchor/xyz</code> est réécrit en
+<code>/bigpage.html#xyz</code>. En l'absence du drapeau [NE], le #
+aurait été converti en son équivalent hexadécimal, <code>%23</code>, ce
+qui aurait provoqué un code d'erreur "404 Not Found".
+</p>
+
+</section>
+
+<section id="flag_ns"><title>NS|nosubreq</title>
+<p>Le drapeau [NS] empêche la règle de s'appliquer aux sous-requêtes.
+Par exemple, une page incluse au moyen d'une SSI (Server
+Side Include) est une sous-requête, et vous ne voudrez probablement pas que
+la réécriture s'applique à ces sous-requêtes. Ainsi, lorsque
+<module>mod_dir</module> recherche des informations à propos des
+fichiers par défaut du répertoire (comme les fichiers
+<code>index.html</code>), il s'agit d'une sous-requête interne, et vous
+ne désirez en général pas que ces sous-requêtes soient réécrites. Cette
+réécriture
+n'est pas toujours utile pour les sous-requêtes, et peut même causer des
+erreurs si l'ensemble du jeu de règles est appliqué. L'utilisation de
+ce drapeau permet d'exclure les règles qui peuvent poser problème.</p>
+
+<p>Comment déterminer si vous devez utiliser cette règle ou non : si
+vous préfixez les URLs avec des scripts CGI, afin de forcer leur
+traitement par le script CGI, vous vous exposez à des problèmes (ou du
+moins à une surcharge significative) avec les sous-requêtes. Dans ces
+cas, vous devez utiliser ce drapeau.</p>
+
+<p>
+Les images, scripts java, ou fichiers css, chargés en tant que partie
+d'une page html, ne sont pas des sous-requêtes - le navigateur les
+appelle sous forme de requêtes HTTP à part entière.
+</p>
+</section>
+
+<section id="flag_p"><title>P|proxy</title>
+<p>L'utilisation du drapeau [P] entraîne le traitement de la requête par
+le module <module>mod_proxy</module>, et ceci via une requête de
+mandataire. Par exemple, si vous voulez que toutes les requêtes d'images
+soient traitées par un serveur d'images annexe, vous pouvez utiliser
+une règle de ce style :</p>
+
+<example>
+RewriteRule (.*)\.(jpg|gif|png) http://images.example.com$1.$2 [P]
+</example>
+
+<p>L'utilisation du drapeau [P] provoque aussi l'effet du drapeau [L] -
+autrement dit, la requête est immédiatement envoyée au mandataire, et
+toute règle ultérieure sera ignorée.</p>
+
+<p>
+Vous devez vous assurer que la chaîne de substitution soit un URI valide
+(commençant typiquement par <code>http://</code><em>nom-serveur</em>)
+qui puisse être traitée par le module <module>mod_proxy</module>. Dans
+le cas contraire, le module mandataire vous renverra une erreur.
+L'utilisation de ce drapeau implémente de manière plus puissante la
+directive <directive module="mod_proxy">ProxyPass</directive>, pour
+faire correspondre le contenu distant à l'espace de nommage du serveur
+local.</p>
+
+<p>Note: <module>mod_proxy</module> doit être activé pour pouvoir
+utiliser ce drapeau.</p>
+
+</section>
+
+<section id="flag_pt"><title>PT|passthrough</title>
+
+<p>
+Par défaut, la cible (ou chaîne de substitution) d'une règle
+RewriteRule est sensée être un chemin de fichier. Avec le drapeau [PT],
+par contre, elle est traitée comme un URI. Autrement dit, avec le
+drapeau [PT], le résultat de la règle <directive
+module="mod_rewrite">RewriteRule</directive> est passé à nouveau au
+système de mise en correspondance des URLs avec le système de fichiers,
+de façon à ce que les systèmes de mise en correspondance basés sur les
+chemins de fichiers, comme la directive <directive
+module="mod_alias">Alias</directive>, <directive
+module="core">Redirect</directive>, ou <directive
+module="mod_alias">ScriptAlias</directive>, par exemple, puissent avoir une
+chance d'accomplir leur tâche.
+</p>
+
+<p>
+Si par exemple, vous avez un <directive
+module="mod_alias">Alias</directive> pour /icons, et une règle <directive
+module="mod_rewrite">RewriteRule</directive> qui renvoie vers /icons,
+vous devez utiliser le drapeau [PT] pour être sûr que l'<directive
+module="mod_alias">Alias</directive> sera bien évalué.
+</p>
+
+<example>
+Alias /icons /usr/local/apache/icons<br />
+RewriteRule /pics/(.+)\.jpg /icons/$1.gif [PT]
+</example>
+
+<p>
+Dans l'exemple précédent, en l'absence du drapeau [PT], l'Alias aurait
+été ignoré, ce qui aurait provoqué une erreur 'File not found'.
+</p>
+
+<p>Avec le drapeau <code>PT</code>, le drapeau <code>L</code> est
+implicite : la réécriture s'arrêtera afin de transmettre la requête à la
+phase suivante du traitement.</p>
+
+<p>Notez que le drapeau <code>PT</code> est implicite dans des contextes
+de répertoire comme les sections <directive type="section"
+module="core">Directory</directive> ou les fichiers
+<code>.htaccess</code>. Le seul moyen de contourner ceci consiste à
+réécrire vers <code>-</code>.</p>
+
+</section>
+
+<section id="flag_qsa"><title>QSA|qsappend</title>
+<p>
+Quand l'URI de remplacement contient une chaîne de requête, le
+comportement par défaut de la règle <directive
+module="mod_rewrite">RewriteRule</directive> est de supprimer la <code>
+query string</code> (il s'agit des paramètres éventuellement passés dans l'URL après le
+caractère <code>?</code>, usuellement pour les formulaires traités par la
+méthode HTTP <code>GET</code>) existante, et de la remplacer par celle nouvellement créée.
+Avec le drapeau [QSA], les chaînes de requête peuvent être combinées.
+</p>
+
+<p>Considérons la règle suivante :</p>
+
+<example>
+RewriteRule /pages/(.+) /page.php?page=$1 [QSA]
+</example>
+
+<p>Avec le drapeau [QSA], une requête pour
+<code>/pages/123?one=two</code> sera réécrite en
+<code>/page.php?page=123&one=two</code>. Sans le drapeau [QSA], la
+même requête sera réécrite en <code>/page.php?page=123</code> -
+autrement dit, la chaîne de requête (<code>query string</code>) existante sera supprimée.
+</p>
+</section>
+
+<section id="flag_qsd"><title>QSD|qsdiscard</title>
+<p>
+Lorsque l'URI de la requête contient une chaîne de paramètres, et si
+l'URI cible n'en contient pas, le comportement par défaut de la
+directive <directive module="mod_rewrite">RewriteRule</directive> consiste à copier cette
+chaîne de paramètres dans l'URI cible. Avec le drapeau [QSD], la chaîne
+de paramètres est supprimée.
+</p>
+
+<p>Ce drapeau est disponible dans les versions 2.4.0 et supérieures.</p>
+
+<p>
+Lorsque les drapeaux [QSD] et [QSA] sont utilisés ensemble, c'est le
+drapeau [QSD] qui l'emporte.
+</p>
+
+<p>
+Si l'URI cible possède une chaîne de paramètres, le comportement par
+défaut sera respecté - c'est à dire que la chaîne de paramètres
+originale sera supprimée et remplacée par la chaîne de paramètres de
+l'URI cible.
+</p>
+
+</section>
+
+
+<section id="flag_r"><title>R|redirect</title>
+<p>
+L'utilisation du drapeau [R] provoque l'envoi d'une redirection au
+navigateur. Si une URL pleinement qualifiée (FQDN - fully qualified domain name)
+ est spécifiée (c'est à dire incluant <code>http://nom-du-serveur/</code>),
+ une redirection sera effectuée vers cette adresse. Dans le cas contraire,
+ le protocole courant, le nom du serveur et le numéro de port seront
+ utilisés pour générer l'URL envoyée avec la redirection.
+</p>
+
+<p><em>Tout</em> code de statut de réponse HTTP valide peut être
+spécifié, en utilisant la syntaxe [R=305], le code de statut 302 étant
+utilisé par défaut si aucun code n'est spécifié. Le code de statut
+spécifié n'est pas nécessairement un code de statut de redirection (3xx).
+</p>
+
+<p>Si le code de statut est en dehors de la plage des codes de
+redirection (300-399), la chaîne de substitution est entièrement
+supprimée, et la réécriture s'arrête comme si le drapeau <code>L</code>
+était utilisé.</p>
+
+<p>En plus des codes de statut de réponse, vous pouvez spécifier les
+codes de redirection en utilisant leurs noms symboliques :
+<code>temp</code> (défaut), <code>permanent</code>, ou
+<code>seeother</code>.</p>
+
+<p>
+Vous utiliserez presque toujours [R] en conjonction avec [L] (c'est à
+dire [R,L]), car employé seul, le drapeau [R] préfixe l'URI avec
+<code>http://cet-hôte[:ce-port]</code>, mais passe ensuite cette adresse
+à la règle suivante, ce qui provoquera le plus souvent des
+avertissements 'Invalid URI in request'.
+</p>
+
+</section>
+
+<section id="flag_s"><title>S|skip</title>
+<p>Le drapeau [S] sert à sauter des règles que vous ne voulez pas voir
+exécuter. Ceci peut s'interpréter comme une instruction
+<code>goto</code> dans votre jeu de règles de réécriture. Dans
+l'exemple suivant, nous ne voulons exécuter la règle <directive
+module="mod_rewrite">RewriteRule</directive> que si l'URI demandé ne
+correspond pas à un fichier existant.</p>
+
+<example>
+# La requête concerne-t-elle un fichier qui n'existe pas ?<br />
+RewriteCond %{REQUEST_FILENAME} !-f<br />
+RewriteCond %{REQUEST_FILENAME} !-d<br />
+# Si c'est la cas, on saute les deux règles de réécriture suivantes<br />
+RewriteRule .? - [S=2]<br />
+<br />
+RewriteRule (.*\.gif) images.php?$1<br />
+RewriteRule (.*\.html) docs.php?$1
+</example>
+
+<p>Cette technique trouve son utilité dans le fait qu'une directive
+<directive module="mod_rewrite">RewriteCond</directive> ne s'applique
+qu'à la règle qui la suit immédiatement. Ainsi, si vous voulez
+qu'une directive <code>RewriteCond</code> s'applique à plusieurs règles
+<code>RewriteRule</code>, une technique possible consiste à inverser ces
+conditions et à utiliser le drapeau [Skip]. Cette technique permet
+d'élaborer des pseudo-constructions if-then-else : la dernière règle du
+bloc then contiendra <code>skip=N</code>, où N est le nombre de règles
+contenues dans le bloc else.</p>
+
+</section>
+
+<section id="flag_t"><title>T|type</title>
+<p>Définit le type MIME de la réponse résultante renvoyée. L'effet est
+identique à celui de la directive <directive
+module="mod_mime">AddType</directive>.</p>
+
+<p>Par exemple, vous pouvez utiliser la technique suivante pour servir
+du code source Perl en tant que plein texte, s'il est requis d'une
+certaine manière :</p>
+
+<example>
+# Sert les fichier .pl en tant que plein texte<br />
+RewriteRule \.pl$ - [T=text/plain]
+</example>
+
+<p>Ou encore, si vous possédez une caméra qui produit des fichiers
+images jpeg sans extension, vous pouvez forcer le renvoi de ces images
+avec le type MIME correct en se basant sur le nom du fichier :</p>
+
+<example>
+# Les fichiers dont le nom contient 'IMG' sont des images jpg.<br />
+RewriteRule IMG - [T=image/jpg]
+</example>
+
+<p>Notez cependant qu'il s'agit d'un exemple trivial, et que le problème
+aurait pu être résolu en utilisant à la place la directive <directive
+type="section" module="core">FilesMatch</directive>. Il faut toujours
+envisager la possibilité d'une solution alternative à un problème avant
+d'avoir recours à la réécriture, qui sera toujours moins efficace qu'une
+solution alternative.</p>
+
+<p>
+Dans un contexte de niveau répertoire, n'utilisez que <code>-</code>
+(tiret) comme substitution, <em>dans toute la séquence de réécriture de
+mod_rewrite</em>, sinon le type MIME défini avec ce drapeau
+sera perdu suite à un retraitement interne (y compris les séquences de
+réécriture suivantes de mod_rewrite). Dans ce contexte, vous pouvez
+utiliser le drapeau <code>L</code> pour terminer la séquence
+<em>courante</em> de réécriture de mod_rewrite.</p>
+
+</section>
+
+</manualpage>
+
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- GENERATED FROM XML: DO NOT EDIT -->
+
+<metafile reference="flags.xml">
+ <basename>flags</basename>
+ <path>/rewrite/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant>fr</variant>
+ </variants>
+</metafile>
# GENERATED FROM XML -- DO NOT EDIT
-URI: rewrite_intro.html.en
+URI: htaccess.html.en
Content-Language: en
Content-type: text/html; charset=ISO-8859-1
--- /dev/null
+<?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>mod_rewrite and .htaccess files - 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>mod_rewrite and .htaccess files</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/rewrite/htaccess.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 way that the rules change when you use mod_rewrite in .htaccess files,
+and how to deal with these changes.</p>
+
+</div>
+<div id="quickview"><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="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>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/htaccess.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
--- /dev/null
+<?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="htaccess.xml.meta">
+ <parentdocument href="./">Rewrite</parentdocument>
+
+<title>mod_rewrite and .htaccess files</title>
+
+<summary>
+
+<p>This document supplements the <module>mod_rewrite</module>
+<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
+the way that the rules change when you use mod_rewrite in .htaccess files,
+and how to deal with these changes.</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>
+
+</manualpage>
<?xml version="1.0" encoding="UTF-8" ?>
<!-- GENERATED FROM XML: DO NOT EDIT -->
-<metafile reference="rewrite_flags.xml">
- <basename>rewrite_flags</basename>
+<metafile reference="htaccess.xml">
+ <basename>htaccess</basename>
<path>/rewrite/</path>
<relpath>..</relpath>
Content-Language: en
Content-type: text/html; charset=ISO-8859-1
+URI: index.html.fr
+Content-Language: fr
+Content-type: text/html; charset=ISO-8859-1
+
URI: index.html.tr.utf8
Content-Language: tr
Content-type: text/html; charset=UTF-8
<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></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite</h1>
<div class="toplang">
<p><span>Available Languages: </span><a href="../en/rewrite/" title="English"> en </a> |
+<a href="../fr/rewrite/" hreflang="fr" rel="alternate" title="Français"> fr </a> |
<a href="../tr/rewrite/" hreflang="tr" rel="alternate" title="Türkçe"> tr </a> |
<a href="../zh-cn/rewrite/" hreflang="zh-cn" rel="alternate" title="Simplified Chinese"> zh-cn </a></p>
</div>
- <blockquote>
- <p>``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.''</p>
- <p class="cite">-- <cite>Brian Behlendorf</cite><br />
- Apache Group</p>
+ <p><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> provides a way to modify incoming
+ URL requests, dynamically, based on <a href="intro.html#regex">regular
+ expression</a> rules. This allows you to map arbitrary URLs onto
+ your internal URL structure in any way you like.</p>
- </blockquote>
-
- <blockquote>
- <p>``Despite the tons of examples and docs,
- mod_rewrite is voodoo. Damned cool voodoo, but still
- voodoo.''</p>
-
- <p class="cite">-- <cite>Brian Moore</cite><br />
- bem@news.cmc.net</p>
-
- </blockquote>
-
- <p>Welcome to mod_rewrite, the Swiss Army Knife of URL
- manipulation!</p>
-
- <p>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
+ <p>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 granular URL
+ mechanism. The URL manipulations can depend on various tests:
+ server variables, environment variables, HTTP
+ headers, time stamps, external database lookups, and various other
+ external programs or handlers, can be used to achieve granular URL
matching.</p>
- <p>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> files and <code><Directory></code>
- blocks) 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.</p>
+ <p>Rewrite rules can operate on the full URLs, including the path-info
+ and query string portions, and may be used in per-server context
+ (<code>httpd.conf</code>), per-virtualhost context (<code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code> blocks), or
+ per-directory context (<code>.htaccess</code> files and <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> blocks). The
+ rewritten result can lead to further rules, internal
+ sub-processing, external request redirection, or proxy
+ passthrough, depending on what <a href="flags.html">flags</a> you
+ attach to the rules.</p>
+
+ <p>Since mod_rewrite is so powerful, it can indeed be rather
+ complex. This document supplements the <a href="../mod/mod_rewrite.html">reference documentation</a>, and
+ attempts to allay some of that complexity, and provide highly
+ annoted examples of common scenarios that you may handle with
+ mod_rewrite. But we also attempt to show you when you should not
+ use mod_rewrite, and use other standard Apache features instead,
+ thus avoiding this unnecessary complexity.</p>
- <p>But all this functionality and flexibility has its
- drawback: complexity. So don't expect to understand this
- entire module in just one day.</p>
-</div>
-<div id="quickview"><h3>See also</h3><ul class="seealso"><li><a href="../urlmapping.html">Mapping URLs to the Filesystem</a></li><li><a href="http://wiki.apache.org/httpd/Rewrite">mod_rewrite
-wiki</a></li><li><a href="../glossary.html">Glossary</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="documentation" id="documentation">Documentation</a></h2>
<ul>
<li><a href="../mod/mod_rewrite.html">mod_rewrite reference
documentation</a></li>
-<li><a href="rewrite_intro.html">Introduction</a></li>
-<li><a href="rewrite_flags.html">Flags</a></li>
-<li><a href="rewrite_tech.html">Technical details</a></li>
-<li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li>
-<li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide - more
-useful examples</a></li>
+<li><a href="intro.html">Introduction to regular expressions and mod_rewrite</a></li>
+<li><a href="remapping.html">Using mod_rewrite for redirection and remapping of URLs</a></li>
+<li><a href="access.html">Using mod_rewrite to control access</a></li>
+<li><a href="vhosts.html">Dynamic virtual hosts with mod_rewrite</a></li>
+<li><a href="proxy.html">Dynamic proxying with mod_rewrite</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 <strong>NOT</strong> to use mod_rewrite</a></li>
+<li><a href="flags.html">RewriteRule Flags</a></li>
+<li><a href="tech.html">Technical details</a></li>
</ul>
-</div></div>
+</div>
+<div id="quickview"><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">mod_rewrite reference
+documentation</a></li><li><a href="../urlmapping.html">Mapping URLs to the Filesystem</a></li><li><a href="http://wiki.apache.org/httpd/Rewrite">mod_rewrite
+wiki</a></li><li><a href="../glossary.html">Glossary</a></li></ul></div>
+</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/rewrite/" title="English"> en </a> |
+<a href="../fr/rewrite/" hreflang="fr" rel="alternate" title="Français"> fr </a> |
<a href="../tr/rewrite/" hreflang="tr" rel="alternate" title="Türkçe"> tr </a> |
<a href="../zh-cn/rewrite/" hreflang="zh-cn" rel="alternate" title="Simplified Chinese"> zh-cn </a></p>
</div><div id="footer">
--- /dev/null
+<?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>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></div><div id="page-content"><div id="preamble"><h1>Le module Apache mod_rewrite</h1>
+<div class="toplang">
+<p><span>Langues Disponibles: </span><a href="../en/rewrite/" hreflang="en" rel="alternate" title="English"> en </a> |
+<a href="../fr/rewrite/" title="Français"> fr </a> |
+<a href="../tr/rewrite/" hreflang="tr" rel="alternate" title="Türkçe"> tr </a> |
+<a href="../zh-cn/rewrite/" hreflang="zh-cn" rel="alternate" title="Simplified Chinese"> zh-cn </a></p>
+</div>
+
+
+ <p><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> permet de modifier les requêtes
+ entrantes dynamiquement, en fonction de règles manipulant des <a href="intro.html#regex">expressions rationnelles</a>. Vous pouvez
+ ainsi relier des URLs arbitraires à votre propre structure d'URLs
+ interne comme vous le souhaitez.</p>
+
+ <p>Il fournit un
+ mécanisme de manipulation d'URL particulièrement souple et
+ puissant en supportant un nombre illimité de règles et de
+ conditions attachées à chaque règle. Les manipulations d'URLs
+ peuvent dépendre de tests variés : les URLs peuvent
+ être finement caractérisées en fonction de variables du serveur,
+ de variables d'environnement, d'en-têtes HTTP, de repères
+ temporels, de recherches dans des bases de données
+ externes, ou même de requêtes vers des bases de données externes
+ et de différents gestionnaires ou programmes externes.</p>
+
+ <p>Les règles de réécriture peuvent agir sur l'ensemble des URLs (la partie chemin
+ et la chaîne de paramètres) et peuvent être utilisées dans le contexte du serveur principal
+ (<code>httpd.conf</code>), mais aussi dans le contexte des
+ serveurs virtuels (sections <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code>), ou dans le
+ contexte des
+ répertoires (fichiers <code>.htaccess</code> et blocs
+ <code><Directory></code>. Le résultat
+ réécrit peut conduire vers d'autres règles à un
+ traitement secondaire interne, une redirection vers une requête
+ externe ou même l'envoi vers un serveur mandataire, en fonction
+ des <a href="flags.html">drapeaux</a> que vous attachez aux
+ règles</p>
+
+ <p>mod_rewrite étant très puissant, il peut par
+ conséquent être très complexe. Ce document
+ complè la <a href="../mod/mod_rewrite.html">documentation de
+ référence</a>, et est sensé alléger un
+ peu cette complexité, et présenter des exemples largement
+ commentés, ainsi que des situations courantes que vous
+ pourrez traiter avec mod_rewrite. Mais nous voulons aussi vous
+ montrer des situations où vous ne devrez pas utiliser
+ mod_rewrite, et lui préférer d'autres
+ fonctionnalités standard d'Apache, évitant ainsi
+ d'entrer dans une complexité inutile.</p>
+
+<ul>
+<li><a href="../mod/mod_rewrite.html">documentation de
+référence de mod_rewrite</a></li>
+<li><a href="intro.html">Introduction aux expressions rationnelles et à
+mod_rewrite</a></li>
+<li><a href="rewrite_guide.html">Guide de la réécriture -
+exemples utiles</a></li>
+<li><a href="remapping.html">Utilisation de mod_rewrite pour la
+redirection et la remise en corespondance avec le système de
+fichiers des URLs</a></li>
+<li><a href="access.html">Utilisation de mod_rewrite pour le
+contrôle d'accès</a></li>
+<li><a href="vhosts.html">Les serveurs virtuels dynamiques avec mod_rewrite</a></li>
+<li><a href="proxy.html">Les serveurs mandataires dynamiques avec mod_rewrite</a></li>
+<li><a href="rewritemap.html">Utilisation de RewriteMap</a></li>
+<li><a href="advanced.html">Techniques avancées et conseils</a></li>
+<li><a href="avoid.html">Quand <strong>NE PAS</strong> utiliser mod_rewrite</a></li>
+<li><a href="flags.html">Drapeaux de réécriture</a></li>
+<li><a href="tech.html">Détails techniques</a></li>
+</ul>
+</div>
+<div id="quickview"><h3>Voir aussi</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Documentation de
+référence de mod_rewrite</a></li><li><a href="../urlmapping.html">Mise en correspondance des URLs
+avec le système de fichiers</a></li><li><a href="http://wiki.apache.org/httpd/Rewrite">wiki mod_rewrite
+</a></li><li><a href="../glossary.html">Glossaire</a></li></ul></div>
+</div>
+<div class="bottomlang">
+<p><span>Langues Disponibles: </span><a href="../en/rewrite/" hreflang="en" rel="alternate" title="English"> en </a> |
+<a href="../fr/rewrite/" title="Français"> fr </a> |
+<a href="../tr/rewrite/" hreflang="tr" rel="alternate" title="Türkçe"> tr </a> |
+<a href="../zh-cn/rewrite/" hreflang="zh-cn" rel="alternate" title="Simplified Chinese"> zh-cn </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
<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Sunucusu</a> > <a href="http://httpd.apache.org/docs/">Belgeleme</a> > <a href="../">Sürüm 2.2</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite</h1>
<div class="toplang">
<p><span>Mevcut Diller: </span><a href="../en/rewrite/" hreflang="en" rel="alternate" title="English"> en </a> |
+<a href="../fr/rewrite/" hreflang="fr" rel="alternate" title="Français"> fr </a> |
<a href="../tr/rewrite/" title="Türkçe"> tr </a> |
<a href="../zh-cn/rewrite/" hreflang="zh-cn" rel="alternate" title="Simplified Chinese"> zh-cn </a></p>
</div>
+<div class="outofdate">Bu çeviri güncel olmayabilir. Son değişiklikler için İngilizce sürüm geçerlidir.</div>
<blockquote>
<p>``mod_rewrite’ı harika yapan şey, Sendmail’ın tüm yapılandırma
<h2><a name="documentation" id="documentation">Belgeler</a></h2>
<ul>
<li><a href="../mod/mod_rewrite.html">mod_rewrite Başvuru Kılavuzu</a></li>
- <li><a href="rewrite_intro.html">Giriş</a></li>
- <li><a href="rewrite_flags.html">Seçenekler</a></li>
- <li><a href="rewrite_tech.html">Teknik Ayrıntılar</a></li>
+ <li><a href="intro.html">Giriş</a></li>
+ <li><a href="flags.html">Seçenekler</a></li>
+ <li><a href="tech.html">Teknik Ayrıntılar</a></li>
<li><a href="rewrite_guide.html">Yeniden Yazma Rehberi -
yararlı örnekler</a></li>
<li><a href="rewrite_guide_advanced.html">Gelişkin Yeniden Yazma Rehberi -
</div></div>
<div class="bottomlang">
<p><span>Mevcut Diller: </span><a href="../en/rewrite/" hreflang="en" rel="alternate" title="English"> en </a> |
+<a href="../fr/rewrite/" hreflang="fr" rel="alternate" title="Français"> fr </a> |
<a href="../tr/rewrite/" title="Türkçe"> tr </a> |
<a href="../zh-cn/rewrite/" hreflang="zh-cn" rel="alternate" title="Simplified Chinese"> zh-cn </a></p>
</div><div id="footer">
<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP 服务器</a> > <a href="http://httpd.apache.org/docs/">文档</a> > <a href="../">版本 2.2</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite</h1>
<div class="toplang">
<p><span>可用语言: </span><a href="../en/rewrite/" hreflang="en" rel="alternate" title="English"> en </a> |
+<a href="../fr/rewrite/" hreflang="fr" rel="alternate" title="Français"> fr </a> |
<a href="../tr/rewrite/" hreflang="tr" rel="alternate" title="Türkçe"> tr </a> |
<a href="../zh-cn/rewrite/" title="Simplified Chinese"> zh-cn </a></p>
</div>
- <blockquote>
- <p>``mod_rewrite 最棒的一点是它为 Sendmail
- 提供了所有的可配置性和灵活性。mod_rewrite
- 的缺点也是它为 Sendmail 提供了所有的可配置性和灵活性。''</p>
+ <p><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> 提供了基于<a href="intro.html#regex">正则表达式</a>规则动态修改传入的请求的 URL 的方法。
+ 这允许你以自己喜欢的任意方法映射任意 URL 到你的内部 URL 结构。</p>
- <p class="cite">-- <cite>Brian Behlendorf</cite><br />
- Apache Group</p>
+ <p>它支持无限的规则，以及为每个规则附加条件，从而提供了一个真正灵活且强大的 URL
+ 操作机制。URL 操作可以依赖于各种测试，例如服务器变量，环境变量，HTTP
+ 头，时戳，甚至外部数据库查询等，以便完成 URL 单元匹配。</p>
- </blockquote>
+ <p>这个模块在服务器上下文 (<code>httpd.conf</code>)，虚拟主机上下文 (<code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code> 指令块)，目录上下文
+ (<code>.htaccess</code> 文件和 <code><Directory></code>
+ 指令块) 对完整的 URL (包含目录信息部分和查询字符串部分) 操作。
+ 重写结果可以导致新的规则处理，内部的后续处理，外部请求重定向，甚至透过内部代理，
+ 这取决于你为规则附加的<a href="flags.html">标志</a>。</p>
- <blockquote>
- <p>``尽管有非常多的例子和文档， mod_rewrite 依旧是魔术。
- 该死的魔术，绝妙的魔术，还是魔术。''</p>
+ <p>既然 mod_rewrite 这么强大，它当然是相当复杂。这篇文档作为<a href="../mod/mod_rewrite.html">参考手册</a>的补充，试图减轻一些复杂性，
+ 提供你可能使用 mod_rewrite 的常见场景的有充分注释的例子。
+ 但是，我们也试图告诉你，在什么时候你不应当使用 mod_rewrite，
+ 可以使用其它标准的 Apache 特性来达到目的，以避免无谓的复杂性。</p>
- <p class="cite">-- <cite>Brian Moore</cite><br />
- bem@news.cmc.net</p>
-
- </blockquote>
-
- <p>欢迎使用 mod_rewrite，操作 URL 的瑞士军刀!</p>
-
- <p>这个模块在处理请求时，使用基于规则的重写引擎
- (基于正则表达式解析器) 改写请求的 URL。
- 它支持无限的规则，以及为每个规则附加条件，从而提供了一个真正灵活且强大的 URL
- 操作机制。URL 操作可以依赖于各种测试，例如服务器变量，环境变量，HTTP
- 头，时戳，甚至外部数据库查询等，以便完成 URL 单元匹配。</p>
-
- <p>这个模块在服务器上下文 (<code>httpd.conf</code>)，目录上下文
- (<code>.htaccess</code> 文件和 <code><Directory></code>
- 指令块) 对完整的 URL (包含目录信息部分) 操作，甚至可以在结果中产生查询字符串部分。
- 重写结果可以导致内部的后续处理，外部请求重定向，甚至透过内部代理。</p>
-
- <p>但是所有这些功能和灵活性都有其缺点: 复杂性。因此，你不要期望能在一天内理解这整个模块。</p>
-
-</div>
-<div id="quickview"><h3>参见</h3><ul class="seealso"><li><a href="../urlmapping.html">从 URL 映射到文件系统</a></li><li><a href="http://wiki.apache.org/httpd/Rewrite">mod_rewrite
-wiki</a></li><li><a href="../glossary.html">术语</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="documentation" id="documentation">文档</a></h2>
<ul>
<li><a href="../mod/mod_rewrite.html">mod_rewrite 参考手册</a></li>
-<li><a href="rewrite_intro.html">简介</a></li>
-<li><a href="rewrite_flags.html">标志</a></li>
-<li><a href="rewrite_tech.html">技术细节</a></li>
-<li><a href="rewrite_guide.html">改写指南 - 有用的例子</a></li>
-<li><a href="rewrite_guide_advanced.html">高级改写指南 - 更多有用的例子</a></li>
+<li><a href="intro.html">正则表达式与 mod_rewrite 入门</a></li>
+<li><a href="remapping.html">使用 mod_rewrite 重定向和重新映射 URL</a></li>
+<li><a href="access.html">使用 mod_rewrite 控制访问</a></li>
+<li><a href="vhosts.html">动态虚拟主机与 mod_rewrite</a></li>
+<li><a href="proxy.html">动态代理与 mod_rewrite</a></li>
+<li><a href="rewritemap.html">使用 RewriteMap</a></li>
+<li><a href="advanced.html">高级技术与诀窍</a></li>
+<li><a href="avoid.html">何时 <strong>不要</strong>使用 mod_rewrite</a></li>
+<li><a href="flags.html">RewriteRule 标志</a></li>
+<li><a href="tech.html">技术细节</a></li>
</ul>
-</div></div>
+</div>
+<div id="quickview"><h3>参见</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">mod_rewrite 参考手册</a></li><li><a href="../urlmapping.html">从 URL 映射到文件系统</a></li><li><a href="http://wiki.apache.org/httpd/Rewrite">mod_rewrite
+wiki</a></li><li><a href="../glossary.html">术语</a></li></ul></div>
+</div>
<div class="bottomlang">
<p><span>可用语言: </span><a href="../en/rewrite/" hreflang="en" rel="alternate" title="English"> en </a> |
+<a href="../fr/rewrite/" hreflang="fr" rel="alternate" title="Français"> fr </a> |
<a href="../tr/rewrite/" hreflang="tr" rel="alternate" title="Türkçe"> tr </a> |
<a href="../zh-cn/rewrite/" title="Simplified Chinese"> zh-cn </a></p>
</div><div id="footer">
<title>Apache mod_rewrite</title>
<summary>
- <blockquote>
- <p>``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.''</p>
- <p class="cite">-- <cite>Brian Behlendorf</cite><br />
- Apache Group</p>
+ <p><module>mod_rewrite</module> provides a way to modify incoming
+ URL requests, dynamically, based on <a href="intro.html#regex">regular
+ expression</a> rules. This allows you to map arbitrary URLs onto
+ your internal URL structure in any way you like.</p>
- </blockquote>
-
- <blockquote>
- <p>``Despite the tons of examples and docs,
- mod_rewrite is voodoo. Damned cool voodoo, but still
- voodoo.''</p>
-
- <p class="cite">-- <cite>Brian Moore</cite><br />
- bem@news.cmc.net</p>
-
- </blockquote>
-
- <p>Welcome to mod_rewrite, the Swiss Army Knife of URL
- manipulation!</p>
-
- <p>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
+ <p>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 granular URL
+ mechanism. The URL manipulations can depend on various tests:
+ server variables, environment variables, HTTP
+ headers, time stamps, external database lookups, and various other
+ external programs or handlers, can be used to achieve granular URL
matching.</p>
- <p>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> files and <code><Directory></code>
- blocks) 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.</p>
+ <p>Rewrite rules can operate on the full URLs, including the path-info
+ and query string portions, and may be used in per-server context
+ (<code>httpd.conf</code>), per-virtualhost context (<directive
+ type="section" module="core">VirtualHost</directive> blocks), or
+ per-directory context (<code>.htaccess</code> files and <directive
+ type="section" module="core">Directory</directive> blocks). The
+ rewritten result can lead to further rules, internal
+ sub-processing, external request redirection, or proxy
+ passthrough, depending on what <a href="flags.html">flags</a> you
+ attach to the rules.</p>
+
+ <p>Since mod_rewrite is so powerful, it can indeed be rather
+ complex. This document supplements the <a
+ href="../mod/mod_rewrite.html">reference documentation</a>, and
+ attempts to allay some of that complexity, and provide highly
+ annoted examples of common scenarios that you may handle with
+ mod_rewrite. But we also attempt to show you when you should not
+ use mod_rewrite, and use other standard Apache features instead,
+ thus avoiding this unnecessary complexity.</p>
- <p>But all this functionality and flexibility has its
- drawback: complexity. So don't expect to understand this
- entire module in just one day.</p>
+<ul>
+<li><a href="../mod/mod_rewrite.html">mod_rewrite reference
+documentation</a></li>
+<li><a href="intro.html">Introduction to regular expressions and mod_rewrite</a></li>
+<li><a href="remapping.html">Using mod_rewrite for redirection and remapping of URLs</a></li>
+<li><a href="access.html">Using mod_rewrite to control access</a></li>
+<li><a href="vhosts.html">Dynamic virtual hosts with mod_rewrite</a></li>
+<li><a href="proxy.html">Dynamic proxying with mod_rewrite</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 <strong>NOT</strong> to use mod_rewrite</a></li>
+<li><a href="flags.html">RewriteRule Flags</a></li>
+<li><a href="tech.html">Technical details</a></li>
+</ul>
</summary>
+<seealso><a href="../mod/mod_rewrite.html">mod_rewrite reference
+documentation</a></seealso>
<seealso><a href="../urlmapping.html">Mapping URLs to the Filesystem</a></seealso>
<seealso><a href="http://wiki.apache.org/httpd/Rewrite">mod_rewrite
wiki</a></seealso>
<seealso><a href="../glossary.html">Glossary</a></seealso>
-<section id="documentation"><title>Documentation</title>
-<ul>
-<li><a href="../mod/mod_rewrite.html">mod_rewrite reference
-documentation</a></li>
-<li><a href="rewrite_intro.html">Introduction</a></li>
-<li><a href="rewrite_flags.html">Flags</a></li>
-<li><a href="rewrite_tech.html">Technical details</a></li>
-<li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li>
-<li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide - more
-useful examples</a></li>
-</ul>
-</section>
</manualpage>
--- /dev/null
+<?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 : 1028730 $ -->
+<!-- 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="index.xml.meta">
+<parentdocument href="../"/>
+
+ <title>Le module Apache mod_rewrite</title>
+
+<summary>
+
+ <p><module>mod_rewrite</module> permet de modifier les requêtes
+ entrantes dynamiquement, en fonction de règles manipulant des <a
+ href="intro.html#regex">expressions rationnelles</a>. Vous pouvez
+ ainsi relier des URLs arbitraires à votre propre structure d'URLs
+ interne comme vous le souhaitez.</p>
+
+ <p>Il fournit un
+ mécanisme de manipulation d'URL particulièrement souple et
+ puissant en supportant un nombre illimité de règles et de
+ conditions attachées à chaque règle. Les manipulations d'URLs
+ peuvent dépendre de tests variés : les URLs peuvent
+ être finement caractérisées en fonction de variables du serveur,
+ de variables d'environnement, d'en-têtes HTTP, de repères
+ temporels, de recherches dans des bases de données
+ externes, ou même de requêtes vers des bases de données externes
+ et de différents gestionnaires ou programmes externes.</p>
+
+ <p>Les règles de réécriture peuvent agir sur l'ensemble des URLs (la partie chemin
+ et la chaîne de paramètres) et peuvent être utilisées dans le contexte du serveur principal
+ (<code>httpd.conf</code>), mais aussi dans le contexte des
+ serveurs virtuels (sections <directive
+ type="section" module="core">VirtualHost</directive>), ou dans le
+ contexte des
+ répertoires (fichiers <code>.htaccess</code> et blocs
+ <code><Directory></code>. Le résultat
+ réécrit peut conduire vers d'autres règles à un
+ traitement secondaire interne, une redirection vers une requête
+ externe ou même l'envoi vers un serveur mandataire, en fonction
+ des <a href="flags.html">drapeaux</a> que vous attachez aux
+ règles</p>
+
+ <p>mod_rewrite étant très puissant, il peut par
+ conséquent être très complexe. Ce document
+ complè la <a
+ href="../mod/mod_rewrite.html">documentation de
+ référence</a>, et est sensé alléger un
+ peu cette complexité, et présenter des exemples largement
+ commentés, ainsi que des situations courantes que vous
+ pourrez traiter avec mod_rewrite. Mais nous voulons aussi vous
+ montrer des situations où vous ne devrez pas utiliser
+ mod_rewrite, et lui préférer d'autres
+ fonctionnalités standard d'Apache, évitant ainsi
+ d'entrer dans une complexité inutile.</p>
+
+<ul>
+<li><a href="../mod/mod_rewrite.html">documentation de
+référence de mod_rewrite</a></li>
+<li><a href="intro.html">Introduction aux expressions rationnelles et à
+mod_rewrite</a></li>
+<li><a href="rewrite_guide.html">Guide de la réécriture -
+exemples utiles</a></li>
+<li><a href="remapping.html">Utilisation de mod_rewrite pour la
+redirection et la remise en corespondance avec le système de
+fichiers des URLs</a></li>
+<li><a href="access.html">Utilisation de mod_rewrite pour le
+contrôle d'accès</a></li>
+<li><a href="vhosts.html">Les serveurs virtuels dynamiques avec mod_rewrite</a></li>
+<li><a href="proxy.html">Les serveurs mandataires dynamiques avec mod_rewrite</a></li>
+<li><a href="rewritemap.html">Utilisation de RewriteMap</a></li>
+<li><a href="advanced.html">Techniques avancées et conseils</a></li>
+<li><a href="avoid.html">Quand <strong>NE PAS</strong> utiliser mod_rewrite</a></li>
+<li><a href="flags.html">Drapeaux de réécriture</a></li>
+<li><a href="tech.html">Détails techniques</a></li>
+</ul>
+</summary>
+
+<seealso><a href="../mod/mod_rewrite.html">Documentation de
+référence de mod_rewrite</a></seealso>
+<seealso><a href="../urlmapping.html">Mise en correspondance des URLs
+avec le système de fichiers</a></seealso>
+<seealso><a href="http://wiki.apache.org/httpd/Rewrite">wiki mod_rewrite
+</a></seealso>
+<seealso><a href="../glossary.html">Glossaire</a></seealso>
+
+</manualpage>
+
+
<variants>
<variant>en</variant>
- <variant>tr</variant>
+ <variant>fr</variant>
+ <variant outdated="yes">tr</variant>
<variant>zh-cn</variant>
</variants>
</metafile>
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.tr.xsl"?>
-<!-- English Revision: 636379 -->
+<!-- English Revision: 636374:1028730 (outdated) -->
<!-- =====================================================
Translated by: Nilgün Belma Bugüner <nilgun belgeler.org>
Reviewed by: Orhan Berent <berent belgeler.org>
<section id="documentation"><title>Belgeler</title>
<ul>
<li><a href="../mod/mod_rewrite.html">mod_rewrite Başvuru Kılavuzu</a></li>
- <li><a href="rewrite_intro.html">Giriş</a></li>
- <li><a href="rewrite_flags.html">Seçenekler</a></li>
- <li><a href="rewrite_tech.html">Teknik Ayrıntılar</a></li>
+ <li><a href="intro.html">Giriş</a></li>
+ <li><a href="flags.html">Seçenekler</a></li>
+ <li><a href="tech.html">Teknik Ayrıntılar</a></li>
<li><a href="rewrite_guide.html">Yeniden Yazma Rehberi -
yararlı örnekler</a></li>
<li><a href="rewrite_guide_advanced.html">Gelişkin Yeniden Yazma Rehberi -
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.zh-cn.xsl"?>
-<!-- English revision : 636379 -->
+<!-- English revision : 1028730 -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<title>Apache mod_rewrite</title>
<summary>
- <blockquote>
- <p>``mod_rewrite 最棒的一点是它为 Sendmail
- 提供了所有的可配置性和灵活性。mod_rewrite
- 的缺点也是它为 Sendmail 提供了所有的可配置性和灵活性。''</p>
-
- <p class="cite">-- <cite>Brian Behlendorf</cite><br />
- Apache Group</p>
-
- </blockquote>
-
- <blockquote>
- <p>``尽管有非常多的例子和文档， mod_rewrite 依旧是魔术。
- 该死的魔术，绝妙的魔术，还是魔术。''</p>
-
- <p class="cite">-- <cite>Brian Moore</cite><br />
- bem@news.cmc.net</p>
-
- </blockquote>
-
- <p>欢迎使用 mod_rewrite，操作 URL 的瑞士军刀!</p>
-
- <p>这个模块在处理请求时，使用基于规则的重写引擎
- (基于正则表达式解析器) 改写请求的 URL。
- 它支持无限的规则，以及为每个规则附加条件，从而提供了一个真正灵活且强大的 URL
- 操作机制。URL 操作可以依赖于各种测试，例如服务器变量，环境变量，HTTP
- 头，时戳，甚至外部数据库查询等，以便完成 URL 单元匹配。</p>
-
- <p>这个模块在服务器上下文 (<code>httpd.conf</code>)，目录上下文
- (<code>.htaccess</code> 文件和 <code><Directory></code>
- 指令块) 对完整的 URL (包含目录信息部分) 操作，甚至可以在结果中产生查询字符串部分。
- 重写结果可以导致内部的后续处理，外部请求重定向，甚至透过内部代理。</p>
-
- <p>但是所有这些功能和灵活性都有其缺点: 复杂性。因此，你不要期望能在一天内理解这整个模块。</p>
+ <p><module>mod_rewrite</module> 提供了基于<a
+ href="intro.html#regex">正则表达式</a>规则动态修改传入的请求的 URL 的方法。
+ 这允许你以自己喜欢的任意方法映射任意 URL 到你的内部 URL 结构。</p>
+
+ <p>它支持无限的规则，以及为每个规则附加条件，从而提供了一个真正灵活且强大的 URL
+ 操作机制。URL 操作可以依赖于各种测试，例如服务器变量，环境变量，HTTP
+ 头，时戳，甚至外部数据库查询等，以便完成 URL 单元匹配。</p>
+
+ <p>这个模块在服务器上下文 (<code>httpd.conf</code>)，虚拟主机上下文 (<directive
+ type="section" module="core">VirtualHost</directive> 指令块)，目录上下文
+ (<code>.htaccess</code> 文件和 <code><Directory></code>
+ 指令块) 对完整的 URL (包含目录信息部分和查询字符串部分) 操作。
+ 重写结果可以导致新的规则处理，内部的后续处理，外部请求重定向，甚至透过内部代理，
+ 这取决于你为规则附加的<a href="flags.html">标志</a>。</p>
+
+ <p>既然 mod_rewrite 这么强大，它当然是相当复杂。这篇文档作为<a
+ href="../mod/mod_rewrite.html">参考手册</a>的补充，试图减轻一些复杂性，
+ 提供你可能使用 mod_rewrite 的常见场景的有充分注释的例子。
+ 但是，我们也试图告诉你，在什么时候你不应当使用 mod_rewrite，
+ 可以使用其它标准的 Apache 特性来达到目的，以避免无谓的复杂性。</p>
+<ul>
+<li><a href="../mod/mod_rewrite.html">mod_rewrite 参考手册</a></li>
+<li><a href="intro.html">正则表达式与 mod_rewrite 入门</a></li>
+<li><a href="remapping.html">使用 mod_rewrite 重定向和重新映射 URL</a></li>
+<li><a href="access.html">使用 mod_rewrite 控制访问</a></li>
+<li><a href="vhosts.html">动态虚拟主机与 mod_rewrite</a></li>
+<li><a href="proxy.html">动态代理与 mod_rewrite</a></li>
+<li><a href="rewritemap.html">使用 RewriteMap</a></li>
+<li><a href="advanced.html">高级技术与诀窍</a></li>
+<li><a href="avoid.html">何时 <strong>不要</strong>使用 mod_rewrite</a></li>
+<li><a href="flags.html">RewriteRule 标志</a></li>
+<li><a href="tech.html">技术细节</a></li>
+</ul>
</summary>
+<seealso><a href="../mod/mod_rewrite.html">mod_rewrite 参考手册</a></seealso>
<seealso><a href="../urlmapping.html">从 URL 映射到文件系统</a></seealso>
<seealso><a href="http://wiki.apache.org/httpd/Rewrite">mod_rewrite
wiki</a></seealso>
<seealso><a href="../glossary.html">术语</a></seealso>
-<section id="documentation"><title>文档</title>
-<ul>
-<li><a href="../mod/mod_rewrite.html">mod_rewrite 参考手册</a></li>
-<li><a href="rewrite_intro.html">简介</a></li>
-<li><a href="rewrite_flags.html">标志</a></li>
-<li><a href="rewrite_tech.html">技术细节</a></li>
-<li><a href="rewrite_guide.html">改写指南 - 有用的例子</a></li>
-<li><a href="rewrite_guide_advanced.html">高级改写指南 - 更多有用的例子</a></li>
-</ul>
-</section>
-
</manualpage>
-
-
--- /dev/null
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: intro.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1
+
+URI: intro.html.fr
+Content-Language: fr
+Content-type: text/html; charset=ISO-8859-1
<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 Introduction</h1>
<div class="toplang">
-<p><span>Available Languages: </span><a href="../en/rewrite/rewrite_intro.html" title="English"> en </a></p>
+<p><span>Available Languages: </span><a href="../en/rewrite/intro.html" title="English"> en </a> |
+<a href="../fr/rewrite/intro.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
</div>
<p>This document supplements the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
</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="#regex">Regular Expressions</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#rewriterule">RewriteRule basics</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#rewriterule">RewriteRule Basics</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#flags">Rewrite Flags</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">Rewrite conditions</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">Rewrite Conditions</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#rewritemap">Rewrite maps</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#htaccess">.htaccess files</a></li>
-</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module
-documentation</a></li><li><a href="rewrite_tech.html">Technical details</a></li><li><a href="rewrite_guide.html">Practical solutions to common
-problems</a></li><li><a href="rewrite_guide_advanced.html">Practical solutions to
-advanced problems</a></li></ul></div>
+</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</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="introduction" id="introduction">Introduction</a></h2>
filesystem</a>.</p>
<p>Finally, before proceeding, be sure to configure
-the <code class="directive"><a href="../mod/mod_rewrite.html#rewritelog">RewriteLog</a></code>. Although
-this log file can give an overwhelming amount of information, it is
-indispensable in debugging problems with <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
-configuration, since it will tell you exactly how each rule is
-processed.</p>
+<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>'s log level to one of the trace levels using
+the <code class="directive"><a href="../mod/core.html#loglevel">LogLevel</a></code> directive. Although this
+can give an overwhelming amount of information, it is indispensable in
+debugging problems with <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> configuration, since
+it will tell you exactly how each rule is processed.</p>
+
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="regex" id="regex">Regular Expressions</a></h2>
which can be used with the strings <code>$N</code> and
<code>%N</code> (see below). These are available for creating
the strings <em>Substitution</em> and <em>TestString</em>.
- Figure 2 shows to which locations the back-references are
- transferred for expansion.</p>
+ Figure 1 shows to which locations the back-references are
+ transferred for expansion as well as illustrating the flow of the
+ RewriteRule, RewriteCond matching.</p>
<p class="figure">
- <img src="../images/mod_rewrite_fig2.gif" width="381" height="179" alt="[Needs graphics capability to display]" /><br />
- <dfn>Figure 2:</dfn> The back-reference flow through a rule.
+ <img src="../images/rewrite_rule_flow.png" alt="Flow of RewriteRule and RewriteCond matching" /><br />
+ <dfn>Figure 1:</dfn> The back-reference flow through a rule.
</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
-<h2><a name="rewriterule" id="rewriterule">RewriteRule basics</a></h2>
+<h2><a name="rewriterule" id="rewriterule">RewriteRule Basics</a></h2>
<p>A <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> consists
of three arguments separated by spaces. The arguments are</p>
<ol>
(the part after the hostname but before any question mark indicating
the beginning of a query string).</p>
+<p class="figure">
+ <img src="../images/syntax_rewriterule.png" alt="Syntax of the RewriteRule directive" /><br />
+ <dfn>Figure 2:</dfn> Syntax of the RewriteRule directive.
+</p>
+
+
<p>The <var>Substitution</var> can itself be one of three things:</p>
<dl>
</code></p></div>
<p>For more details on the available flags, their meanings, and
-examples, see the <a href="rewrite_flags.html">Rewrite Flags</a> document.</p>
+examples, see the <a href="flags.html">Rewrite Flags</a> document.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
-<h2><a name="rewritecond" id="rewritecond">Rewrite conditions</a></h2>
+<h2><a name="rewritecond" id="rewritecond">Rewrite Conditions</a></h2>
<p>One or more <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>
directives can be used to restrict the types of requests that will be
subject to the
expression</a> that must match the variable, and a third optional
argument is a list of flags that modify how the match is evaluated.</p>
+<p class="figure">
+ <img src="../images/syntax_rewritecond.png" alt="Syntax of the RewriteCond directive" /><br />
+ <dfn>Figure 3:</dfn> Syntax of the RewriteCond directive
+</p>
+
<p>For example, to send all requests from a particular IP range to a
different server, you could use:</p>
<div class="example"><p><code>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="rewritemap" id="rewritemap">Rewrite maps</a></h2>
-<p>See <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code>.</p>
+
+<p>The <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
+provides a way to call an external function, so to speak, to do your
+rewriting for you. This is discussed in greater detail in the <a href="rewritemap.html">RewriteMap supplementary documentation</a>.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="htaccess" id="htaccess">.htaccess files</a></h2>
</div></div>
<div class="bottomlang">
-<p><span>Available Languages: </span><a href="../en/rewrite/rewrite_intro.html" title="English"> en </a></p>
+<p><span>Available Languages: </span><a href="../en/rewrite/intro.html" title="English"> en </a> |
+<a href="../fr/rewrite/intro.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>
--- /dev/null
+<?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>Introduction au 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>Introduction au module Apache mod_rewrite</h1>
+<div class="toplang">
+<p><span>Langues Disponibles: </span><a href="../en/rewrite/intro.html" hreflang="en" rel="alternate" title="English"> en </a> |
+<a href="../fr/rewrite/intro.html" title="Français"> fr </a></p>
+</div>
+
+<p>Ce document est un complément à la <a href="../mod/mod_rewrite.html">documentation de référence</a> du module
+<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. Il décrit les concepts de base dont la
+connaissance est nécessaire pour l'utilisation de
+<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. D'autres documents entrent d'avantage dans
+les détails, mais celui-ci devrait aider le débutant à se mouiller les
+pieds.
+</p>
+</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="#regex">Expressions rationnelles</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#rewriterule">Les bases des règles de réécriture</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flags">Drapeaux de réécriture</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">Conditions de réécriture</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#rewritemap">Tables de réécriture</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#htaccess">Fichiers .htaccess</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="remapping.html">Redirection and 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 conseils</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="introduction" id="introduction">Introduction</a></h2>
+<p>Le module Apache <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> est un module puissant
+et sophistiqué qui permet la réécriture des URLs. Grâce à lui, vous
+pouvez effectuer quasiment tous les types de réécriture d'URLs dont vous
+avez besoin. Il est cependant assez complexe, et peut paraître
+intimidant au débutant. Certains ont aussi tendance à traiter les
+règles de réécriture comme des incantations magiques, et à les utiliser
+sans vraiment comprendre leur manière d'agir.</p>
+
+<p>Ce document a pour ambition d'être suffisamment explicite pour
+permettre la compréhension, et non la copie en aveugle, de ce qui suit.
+</p>
+
+<p>Gardez à l'esprit que de nombreuses tâches de manipulation d'URLs
+courantes n'ont pas besoin de la puissance et de la complexité de
+<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. Pour les tâches simples, voir
+<code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> et la documentation sur la <a href="../urlmapping.html">Mise en correspondance des URLs avec le
+système de fichiers</a>.</p>
+
+<p>Enfin, avant de procéder, assurez-vous d'avoir configuré le niveau de
+journalisation de <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> à un des niveaux de trace
+via la directive <code class="directive"><a href="../mod/core.html#loglevel">LogLevel</a></code>. Bien que
+ceci risque de vous submerger sous une énorme quantité d'informations,
+le débogage des problèmes avec la configuration de
+<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> est à ce prix car vous verrez alors
+exactement comment chaque règle est traitée.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="regex" id="regex">Expressions rationnelles</a></h2>
+
+<p>mod_rewrite utilise le vocabulaire des <a href="http://pcre.org/">Expressions rationnelles compatibles Perl</a>.
+Ce document n'a pas pour prétention d'être une référence détaillée des
+expressions rationnelles. A cet effet, nous recommandons les <a href="http://pcre.org/pcre.txt">pages de manuel de PCRE</a>, la <a href="http://perldoc.perl.org/perlre.html">page de manuel des
+expressions rationnelles Perl</a>, et l'ouvrage <a href="http://www.oreilly.com/catalog/regex2/index.html">Mastering
+Regular Expressions, by Jeffrey Friedl</a>.</p>
+
+<p>Dans ce document, nous avons pour but de vous fournir suffisamment de
+vocabulaire des expressions rationnelles pour vous mettre le pied à
+l'étrier, sans être dépassé, en espérant que les directives <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> vous apparaîtront comme des
+formules scientifiques, plutôt que comme des incantations magiques.</p>
+
+<h3><a name="regexvocab" id="regexvocab">Vocabulaire des expressions rationnelles</a></h3>
+
+<p>Vous trouverez dans ce qui suit le minimum à connaître pour être en
+mesure d'écrire des expressions rationnelles et des règles <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. Ceci ne représente
+certainement pas un vocabulaire des expressions rationnelles complet,
+mais constitue un bon point de départ, et devrait vous aider à
+déchiffrer les expressions rationnelles simples, et à écrire vos propres
+expressions.</p>
+
+<table>
+<tr>
+<th>Motif</th>
+<th>Signification</th>
+<th>Exemple</th>
+</tr>
+
+<tr><td><code>.</code></td><td>Correspond à tout caractère unique
+</td><td><code>c.t</code> correspondra à <code>cat</code>,
+<code>cot</code>, <code>cut</code>, etc.</td></tr>
+<tr><td><code>+</code></td><td>Répète le caractère de correspondance
+précédent une ou plusieurs fois</td>
+<td><code>a+</code> correspond à <code>a</code>, <code>aa</code>,
+<code>aaa</code>, etc.</td></tr>
+<tr><td><code>*</code></td><td>Répète le caractère de correspondance
+précédent zéro ou plusieurs fois</td>
+<td><code>a*</code> correspond à tout ce à quoi correspond
+<code>a+</code>, mais correspond aussi à la chaîne vide.</td></tr>
+<tr><td><code>?</code></td><td>Rend la correspondance optionnelle.</td><td>
+<code>colou?r</code> correspondra à <code>color</code> et <code>colour</code>.</td>
+</tr>
+<tr><td><code>^</code></td><td>Appelé ancrage, correspond au début de la
+chaîne</td>
+<td><code>^a</code> correspond à une chaîne qui commence par
+<code>a</code></td></tr>
+<tr><td><code>$</code></td><td>L'autre ancrage, correspond à la fin de
+la chaîne.</td>
+<td><code>a$</code> correspond à une chaîne qui se termine par
+<code>a</code>.</td></tr>
+<tr><td><code>( )</code></td><td>Regroupe plusieurs caractères en une
+seule entité, et conserve une correspondance à des fins d'utilisation
+dans une référence arrière.</td>
+<td><code>(ab)+</code>
+correspond à <code>ababab</code> - à savoir, le <code>+</code>
+s'applique au groupe.
+Pour plus de détails sur les références arrières, voir <a href="#InternalBackRefs">ci-dessous</a>.</td></tr>
+<tr><td><code>[ ]</code></td><td>Une classe de caractères - correspond à
+un des caractères de la classe</td>
+<td><code>c[uoa]t</code> correspond à <code>cut</code>,
+<code>cot</code> ou <code>cat</code>.</td></tr>
+<tr><td><code>[^ ]</code></td><td>Négation de la classe de caractères -
+correspond à tout caractère ne faisant pas partie de la classe</td>
+<td><code>c[^/]t</code> correspond à <code>cat</code> ou
+<code>c=t</code> mais pas à <code>c/t</code></td></tr>
+</table>
+
+<p>Avec <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>, le caractère <code>!</code> peut
+préfixer une expression rationnelle afin d'en exprimer la négation.
+Autrement dit, une chaîne ne correspondra que si elle ne correspond pas
+à l'expression située après le <code>!</code>.</p>
+
+
+
+<h3><a name="InternalBackRefs" id="InternalBackRefs">Disponibilité des références
+arrières dans les expressions rationnelles</a></h3>
+
+ <p>Vous devez vous souvenir d'une chose importante : chaque fois
+ que vous utilisez des parenthèses dans un <em>Modèle</em> ou dans
+ un des <em>modèles de conditions</em>, des références arrières
+ sont créées en interne et peuvent être rappelées via les chaînes
+ <code>$N</code> et <code>%N</code> (voir ci-dessous). Ces
+ références sont disponibles lors de la création des chaînes de
+ <em>Substitution</em> et des <em>Chaînes de test</em>. La
+ figure 1
+ montre à quels endroits les références arrières sont suceptibles
+ d'être développées, et illustre le flux des comparaisons
+ effectuées par les règles RewriteRule et RewriteCond.</p>
+
+<p class="figure">
+ <img src="../images/rewrite_rule_flow.png" alt="Flux des comparaisons effectuées par les règles RewriteRule et RewriteCond" /><br />
+ <dfn>Figure 1 :</dfn> Le cheminement d'une référence arrière à
+ travers une règle.
+</p>
+
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="rewriterule" id="rewriterule">Les bases des règles de réécriture</a></h2>
+<p>Une règle de réécriture <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> est constituée de trois
+arguments séparés par des espaces. Les arguments sont :</p>
+<ol>
+<li><var>Modèle</var>: le modèle des URLs auxquelles la règle doit
+s'appliquer;</li>
+<li><var>Substitution</var>: vers quoi la requête correspondante doit être
+transformée;</li>
+<li><var>[drapeaux]</var>: options affectant la requête réécrite.</li>
+</ol>
+
+<p>Le <var>Modèle</var> est toujours une <a href="#regex">expression
+rationnelle</a> comparée au chemin de l'URL de la requête entrante (la
+partie située après le nom d'hôte mais avant tout point d'interrogation
+qui indique le début d'une chaîne de requête).</p>
+
+<p class="figure">
+ <img src="../images/syntax_rewriterule.png" alt="Syntaxe de la directive RewriteRule" /><br />
+ <dfn>Figure 2 :</dfn> Syntaxe de la directive RewriteRule.
+</p>
+
+<p>La chaîne de <var>Substitution</var> peut, quant à elle, être de
+trois types :</p>
+
+<dl>
+<dt>Un chemin complet du système de fichiers vers une ressource</dt>
+<dd>
+<div class="example"><p><code>
+RewriteRule ^/jeux.* /usr/local/jeux/web
+</code></p></div>
+<p>Ceci peut faire correspondre une requête à toute localisation voulue de
+votre système de fichiers, un peu comme la directive <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>.</p>
+</dd>
+
+<dt>Un chemin web vers une ressource</dt>
+<dd>
+<div class="example"><p><code>
+RewriteRule ^/foo$ /bar
+</code></p></div>
+<p>Si la directive <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> a
+pour valeur <code>/usr/local/apache2/htdocs</code>, cette règle va faire
+correspondre les requêtes pour <code>http://example.com/foo</code> au
+chemin <code>/usr/local/apache2/htdocs/bar</code>.</p>
+</dd>
+
+<dt>Une URL absolue</dt>
+<dd>
+<div class="example"><p><code>
+RewriteRule ^/produits/vues$ http://site2.example.com/voirproduits.html [R]
+</code></p></div>
+<p>Ceci informe le client qu'il doit effectuer une nouvelle requête vers
+l'URL spécifiée.</p>
+</dd>
+</dl>
+
+<p>La chaîne de <var>Substitution</var> peut aussi contenir des
+<em>références arrières</em> vers des parties du chemin d'URL entrant
+correspondant au <var>Modèle</var>. Considérons ce qui suit :</p>
+<div class="example"><p><code>
+RewriteRule ^/produits/(.*)/view$ /var/web/produitsdb/$1
+</code></p></div>
+<p>La variable <code>$1</code> sera remplacée par tout texte
+correspondant à l'expression située entre les parenthèses dans le
+<var>Modèle</var>. Par exemple, une requête pour
+<code>http://example.com/produits/r14df/vue</code> correspondra au
+chemin <code>/var/web/produitsdb/r14df</code>.</p>
+
+<p>S'il y a plus d'une expression entre parenthèses, elle seront
+accessibles selon leur ordre d'apparition via les variables
+<code>$1</code>, <code>$2</code>, <code>$3</code>, etc...</p>
+
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="flags" id="flags">Drapeaux de réécriture</a></h2>
+<p>Le comportement d'une règle <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> peut être modifié par la
+présence d'un ou plusieurs drapeaux en fin de règle. Par exemple, les
+conditions de correspondance d'une règle peuvent être rendues
+insensibles à la casse par la présence du drapeau <code>[NC]</code> :
+</p>
+<div class="example"><p><code>
+RewriteRule ^puppy.html petitchien.html [NC]
+</code></p></div>
+
+<p>Pour une liste des drapeaux disponibles, leurs significations, et des
+exemples, voir le document <a href="flags.html">Drapeaux de
+réécriture</a>.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="rewritecond" id="rewritecond">Conditions de réécriture</a></h2>
+<p>Il est possible d'utiliser une ou plusieurs directives <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> pour restreindre les types
+de requêtes auxquelles devra s'appliquer la règle <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> suivante. Le premier
+argument est une variable décrivant une caractéristique de la requête,
+le second argument est une <a href="#regex">expression rationnelle</a>
+qui doit correspondre à la variable, et un troisième argument optionnel
+est une liste de drapeaux qui modifient la manière dont la
+correspondance est évaluée.</p>
+
+<p class="figure">
+ <img src="../images/syntax_rewritecond.png" alt="Syntaxe de la directive RewriteCond" /><br />
+ <dfn>Figure 3 :</dfn> Syntaxe de la directive RewriteCond
+</p>
+
+
+<p>Par exemple, pour renvoyer toutes les requêtes en provenance d'une
+certaine tranche d'adresses IP vers un autre serveur, vous pouvez
+utiliser :</p>
+<div class="example"><p><code>
+RewriteCond %{REMOTE_ADDR} ^10\.2\.<br />
+RewriteRule (.*) http://intranet.example.com$1
+</code></p></div>
+
+<p>Si vous spécifiez plus d'une directive <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>, ces directives
+doivent toutes être satisfaites pour que la règle <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> suivante s'applique. Par exemple,
+pour interdire les requêtes qui contiennent le mot "hack" dans la chaîne
+de requête, sauf si elles contiennent aussi un cookie contenant le mot
+"go", vous pouvez utiliser :</p>
+<div class="example"><p><code>
+RewriteCond %{QUERY_STRING} hack<br />
+RewriteCond %{HTTP_COOKIE} !go<br />
+RewriteRule .* - [F]
+</code></p></div>
+<p>Notez que le point d'exclamation indique une correspondance négative
+; ainsi, la règle n'est appliquée que si le cookie ne contient pas "go"</p>
+
+<p>Les correspondances dans les expressions rationnelles contenues dans
+les directives <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>
+peuvent constituer des parties de la chaîne de <var>Substitution</var>
+de la règle <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> via
+les variables <code>%1</code>, <code>%2</code>, etc... Par
+exemple, ce qui suit va diriger la requête vers un répertoire différent
+en fonction du nom d'hôte utilisé pour accéder au site :</p>
+<div class="example"><p><code>
+RewriteCond %{HTTP_HOST} (.*)<br />
+RewriteRule ^/(.*) /sites/%1/$1
+</code></p></div>
+<p>Si la requête concernait <code>http://example.com/foo/bar</code>,
+alors <code>%1</code> contiendrait <code>example.com</code> et
+<code>$1</code> contiendrait <code>foo/bar</code>.</p>
+
+
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="rewritemap" id="rewritemap">Tables de réécriture</a></h2>
+
+<p>La directive <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code>
+permet en quelque sorte de faire appel à une fonction externe pour
+effectuer la réécriture à votre place. Tout ceci est décrit plus en
+détails dans la <a href="rewritemap.html">Documentation
+supplémentaire sur RewriteMap</a>.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="htaccess" id="htaccess">Fichiers .htaccess</a></h2>
+
+<p>La réécriture est en général définie au niveau de la configuration du
+serveur principal (en dehors de toute section <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>) ou dans une section <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code>. Il s'agit là de la
+manière la plus simple de mettre en oeuvre la réécriture et nous la
+recommandons. Il est possible, cependant, de mettre en oeuvre la
+réécriture au sein d'une section <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> ou d'un fichier <a href="../howto/htaccess.html"><code>.htaccess</code></a> ; ce type de
+configuration est cependant plus complexe. Cette technique est appelée
+réécriture par répertoire.</p>
+
+<p>La principale différence avec les réécritures au niveau du serveur réside
+dans le fait que le préfixe du chemin du répertoire contenant le fichier
+<code>.htaccess</code> est supprimé avant la mise en correspondance dans
+la règle <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. De
+plus, on doit utiliser la directive <code class="directive"><a href="../mod/mod_rewrite.html#rewritebase">RewriteBase</a></code> pour s'assurer que la
+requête est correctement mise en correspondance.</p>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Langues Disponibles: </span><a href="../en/rewrite/intro.html" hreflang="en" rel="alternate" title="English"> en </a> |
+<a href="../fr/rewrite/intro.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
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<!-- $LastChangedRevision$ -->
+<!-- $LastChangedRevision: 1031038 $ -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
limitations under the License.
-->
-<manualpage metafile="rewrite_intro.xml.meta">
+<manualpage metafile="intro.xml.meta">
<parentdocument href="./">Rewrite</parentdocument>
<title>Apache mod_rewrite Introduction</title>
</p>
</summary>
-<seealso><a href="../mod/mod_rewrite.html">Module
-documentation</a></seealso>
-<seealso><a href="rewrite_tech.html">Technical details</a></seealso>
-<seealso><a href="rewrite_guide.html">Practical solutions to common
-problems</a></seealso>
-<seealso><a href="rewrite_guide_advanced.html">Practical solutions to
-advanced problems</a></seealso>
+<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="introduction"><title>Introduction</title>
<p>The Apache module <module>mod_rewrite</module> is a very powerful and
filesystem</a>.</p>
<p>Finally, before proceeding, be sure to configure
-the <directive module="mod_rewrite">RewriteLog</directive>. Although
-this log file can give an overwhelming amount of information, it is
-indispensable in debugging problems with <module>mod_rewrite</module>
-configuration, since it will tell you exactly how each rule is
-processed.</p>
+<module>mod_rewrite</module>'s log level to one of the trace levels using
+the <directive module="core">LogLevel</directive> directive. Although this
+can give an overwhelming amount of information, it is indispensable in
+debugging problems with <module>mod_rewrite</module> configuration, since
+it will tell you exactly how each rule is processed.</p>
+
</section>
<section id="regex"><title>Regular Expressions</title>
which can be used with the strings <code>$N</code> and
<code>%N</code> (see below). These are available for creating
the strings <em>Substitution</em> and <em>TestString</em>.
- Figure 2 shows to which locations the back-references are
- transferred for expansion.</p>
+ Figure 1 shows to which locations the back-references are
+ transferred for expansion as well as illustrating the flow of the
+ RewriteRule, RewriteCond matching.</p>
<p class="figure">
- <img src="../images/mod_rewrite_fig2.gif" width="381"
- height="179" alt="[Needs graphics capability to display]" /><br />
- <dfn>Figure 2:</dfn> The back-reference flow through a rule.
+ <img src="../images/rewrite_rule_flow.png"
+ alt="Flow of RewriteRule and RewriteCond matching" /><br />
+ <dfn>Figure 1:</dfn> The back-reference flow through a rule.
</p>
</section>
</section>
-<section id="rewriterule"><title>RewriteRule basics</title>
+<section id="rewriterule"><title>RewriteRule Basics</title>
<p>A <directive module="mod_rewrite">RewriteRule</directive> consists
of three arguments separated by spaces. The arguments are</p>
<ol>
(the part after the hostname but before any question mark indicating
the beginning of a query string).</p>
+<p class="figure">
+ <img src="../images/syntax_rewriterule.png"
+ alt="Syntax of the RewriteRule directive" /><br />
+ <dfn>Figure 2:</dfn> Syntax of the RewriteRule directive.
+</p>
+
+
<p>The <var>Substitution</var> can itself be one of three things:</p>
<dl>
</example>
<p>For more details on the available flags, their meanings, and
-examples, see the <a href="rewrite_flags.html">Rewrite Flags</a> document.</p>
+examples, see the <a href="flags.html">Rewrite Flags</a> document.</p>
</section>
-<section id="rewritecond"><title>Rewrite conditions</title>
+<section id="rewritecond"><title>Rewrite Conditions</title>
<p>One or more <directive module="mod_rewrite">RewriteCond</directive>
directives can be used to restrict the types of requests that will be
subject to the
expression</a> that must match the variable, and a third optional
argument is a list of flags that modify how the match is evaluated.</p>
+<p class="figure">
+ <img src="../images/syntax_rewritecond.png"
+ alt="Syntax of the RewriteCond directive" /><br />
+ <dfn>Figure 3:</dfn> Syntax of the RewriteCond directive
+</p>
+
<p>For example, to send all requests from a particular IP range to a
different server, you could use:</p>
<example>
</section>
<section id="rewritemap"><title>Rewrite maps</title>
-<p>See <directive module="mod_rewrite">RewriteMap</directive>.</p>
+
+<p>The <directive module="mod_rewrite">RewriteMap</directive> directive
+provides a way to call an external function, so to speak, to do your
+rewriting for you. This is discussed in greater detail in the <a
+href="rewritemap.html">RewriteMap supplementary documentation</a>.</p>
</section>
<section id="htaccess"><title>.htaccess files</title>
</manualpage>
+
--- /dev/null
+<?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 : 1031038 -->
+<!-- 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="intro.xml.meta">
+<parentdocument href="./">Rewrite</parentdocument>
+
+ <title>Introduction au module Apache mod_rewrite</title>
+
+<summary>
+<p>Ce document est un complément à la <a
+href="../mod/mod_rewrite.html">documentation de référence</a> du module
+<module>mod_rewrite</module>. Il décrit les concepts de base dont la
+connaissance est nécessaire pour l'utilisation de
+<module>mod_rewrite</module>. D'autres documents entrent d'avantage dans
+les détails, mais celui-ci devrait aider le débutant à se mouiller les
+pieds.
+</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 and 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 conseils</a></seealso>
+<seealso><a href="avoid.html">Quand ne pas utiliser mod_rewrite</a></seealso>
+
+<section id="introduction"><title>Introduction</title>
+<p>Le module Apache <module>mod_rewrite</module> est un module puissant
+et sophistiqué qui permet la réécriture des URLs. Grâce à lui, vous
+pouvez effectuer quasiment tous les types de réécriture d'URLs dont vous
+avez besoin. Il est cependant assez complexe, et peut paraître
+intimidant au débutant. Certains ont aussi tendance à traiter les
+règles de réécriture comme des incantations magiques, et à les utiliser
+sans vraiment comprendre leur manière d'agir.</p>
+
+<p>Ce document a pour ambition d'être suffisamment explicite pour
+permettre la compréhension, et non la copie en aveugle, de ce qui suit.
+</p>
+
+<p>Gardez à l'esprit que de nombreuses tâches de manipulation d'URLs
+courantes n'ont pas besoin de la puissance et de la complexité de
+<module>mod_rewrite</module>. Pour les tâches simples, voir
+<module>mod_alias</module> et la documentation sur la <a
+href="../urlmapping.html">Mise en correspondance des URLs avec le
+système de fichiers</a>.</p>
+
+<p>Enfin, avant de procéder, assurez-vous d'avoir configuré le niveau de
+journalisation de <module>mod_rewrite</module> à un des niveaux de trace
+via la directive <directive module="core">LogLevel</directive>. Bien que
+ceci risque de vous submerger sous une énorme quantité d'informations,
+le débogage des problèmes avec la configuration de
+<module>mod_rewrite</module> est à ce prix car vous verrez alors
+exactement comment chaque règle est traitée.</p>
+
+</section>
+
+<section id="regex"><title>Expressions rationnelles</title>
+
+<p>mod_rewrite utilise le vocabulaire des <a
+href="http://pcre.org/">Expressions rationnelles compatibles Perl</a>.
+Ce document n'a pas pour prétention d'être une référence détaillée des
+expressions rationnelles. A cet effet, nous recommandons les <a
+href="http://pcre.org/pcre.txt">pages de manuel de PCRE</a>, la <a
+href="http://perldoc.perl.org/perlre.html">page de manuel des
+expressions rationnelles Perl</a>, et l'ouvrage <a
+href="http://www.oreilly.com/catalog/regex2/index.html">Mastering
+Regular Expressions, by Jeffrey Friedl</a>.</p>
+
+<p>Dans ce document, nous avons pour but de vous fournir suffisamment de
+vocabulaire des expressions rationnelles pour vous mettre le pied à
+l'étrier, sans être dépassé, en espérant que les directives <directive
+module="mod_rewrite">RewriteRule</directive> vous apparaîtront comme des
+formules scientifiques, plutôt que comme des incantations magiques.</p>
+
+<section id="regexvocab"><title>Vocabulaire des expressions rationnelles</title>
+
+<p>Vous trouverez dans ce qui suit le minimum à connaître pour être en
+mesure d'écrire des expressions rationnelles et des règles <directive
+module="mod_rewrite">RewriteRule</directive>. Ceci ne représente
+certainement pas un vocabulaire des expressions rationnelles complet,
+mais constitue un bon point de départ, et devrait vous aider à
+déchiffrer les expressions rationnelles simples, et à écrire vos propres
+expressions.</p>
+
+<table>
+<tr>
+<th>Motif</th>
+<th>Signification</th>
+<th>Exemple</th>
+</tr>
+
+<tr><td><code>.</code></td><td>Correspond à tout caractère unique
+</td><td><code>c.t</code> correspondra à <code>cat</code>,
+<code>cot</code>, <code>cut</code>, etc.</td></tr>
+<tr><td><code>+</code></td><td>Répète le caractère de correspondance
+précédent une ou plusieurs fois</td>
+<td><code>a+</code> correspond à <code>a</code>, <code>aa</code>,
+<code>aaa</code>, etc.</td></tr>
+<tr><td><code>*</code></td><td>Répète le caractère de correspondance
+précédent zéro ou plusieurs fois</td>
+<td><code>a*</code> correspond à tout ce à quoi correspond
+<code>a+</code>, mais correspond aussi à la chaîne vide.</td></tr>
+<tr><td><code>?</code></td><td>Rend la correspondance optionnelle.</td><td>
+<code>colou?r</code> correspondra à <code>color</code> et <code>colour</code>.</td>
+</tr>
+<tr><td><code>^</code></td><td>Appelé ancrage, correspond au début de la
+chaîne</td>
+<td><code>^a</code> correspond à une chaîne qui commence par
+<code>a</code></td></tr>
+<tr><td><code>$</code></td><td>L'autre ancrage, correspond à la fin de
+la chaîne.</td>
+<td><code>a$</code> correspond à une chaîne qui se termine par
+<code>a</code>.</td></tr>
+<tr><td><code>( )</code></td><td>Regroupe plusieurs caractères en une
+seule entité, et conserve une correspondance à des fins d'utilisation
+dans une référence arrière.</td>
+<td><code>(ab)+</code>
+correspond à <code>ababab</code> - à savoir, le <code>+</code>
+s'applique au groupe.
+Pour plus de détails sur les références arrières, voir <a
+href="#InternalBackRefs">ci-dessous</a>.</td></tr>
+<tr><td><code>[ ]</code></td><td>Une classe de caractères - correspond à
+un des caractères de la classe</td>
+<td><code>c[uoa]t</code> correspond à <code>cut</code>,
+<code>cot</code> ou <code>cat</code>.</td></tr>
+<tr><td><code>[^ ]</code></td><td>Négation de la classe de caractères -
+correspond à tout caractère ne faisant pas partie de la classe</td>
+<td><code>c[^/]t</code> correspond à <code>cat</code> ou
+<code>c=t</code> mais pas à <code>c/t</code></td></tr>
+</table>
+
+<p>Avec <module>mod_rewrite</module>, le caractère <code>!</code> peut
+préfixer une expression rationnelle afin d'en exprimer la négation.
+Autrement dit, une chaîne ne correspondra que si elle ne correspond pas
+à l'expression située après le <code>!</code>.</p>
+
+</section>
+
+<section id="InternalBackRefs"><title>Disponibilité des références
+arrières dans les expressions rationnelles</title>
+
+ <p>Vous devez vous souvenir d'une chose importante : chaque fois
+ que vous utilisez des parenthèses dans un <em>Modèle</em> ou dans
+ un des <em>modèles de conditions</em>, des références arrières
+ sont créées en interne et peuvent être rappelées via les chaînes
+ <code>$N</code> et <code>%N</code> (voir ci-dessous). Ces
+ références sont disponibles lors de la création des chaînes de
+ <em>Substitution</em> et des <em>Chaînes de test</em>. La
+ figure 1
+ montre à quels endroits les références arrières sont suceptibles
+ d'être développées, et illustre le flux des comparaisons
+ effectuées par les règles RewriteRule et RewriteCond.</p>
+
+<p class="figure">
+ <img src="../images/rewrite_rule_flow.png"
+ alt="Flux des comparaisons effectuées par les règles RewriteRule
+ et RewriteCond" /><br />
+ <dfn>Figure 1 :</dfn> Le cheminement d'une référence arrière à
+ travers une règle.
+</p>
+
+</section>
+</section>
+
+<section id="rewriterule"><title>Les bases des règles de réécriture</title>
+<p>Une règle de réécriture <directive
+module="mod_rewrite">RewriteRule</directive> est constituée de trois
+arguments séparés par des espaces. Les arguments sont :</p>
+<ol>
+<li><var>Modèle</var>: le modèle des URLs auxquelles la règle doit
+s'appliquer;</li>
+<li><var>Substitution</var>: vers quoi la requête correspondante doit être
+transformée;</li>
+<li><var>[drapeaux]</var>: options affectant la requête réécrite.</li>
+</ol>
+
+<p>Le <var>Modèle</var> est toujours une <a href="#regex">expression
+rationnelle</a> comparée au chemin de l'URL de la requête entrante (la
+partie située après le nom d'hôte mais avant tout point d'interrogation
+qui indique le début d'une chaîne de requête).</p>
+
+<p class="figure">
+ <img src="../images/syntax_rewriterule.png"
+ alt="Syntaxe de la directive RewriteRule" /><br />
+ <dfn>Figure 2 :</dfn> Syntaxe de la directive RewriteRule.
+</p>
+
+<p>La chaîne de <var>Substitution</var> peut, quant à elle, être de
+trois types :</p>
+
+<dl>
+<dt>Un chemin complet du système de fichiers vers une ressource</dt>
+<dd>
+<example>
+RewriteRule ^/jeux.* /usr/local/jeux/web
+</example>
+<p>Ceci peut faire correspondre une requête à toute localisation voulue de
+votre système de fichiers, un peu comme la directive <directive
+module="mod_alias">Alias</directive>.</p>
+</dd>
+
+<dt>Un chemin web vers une ressource</dt>
+<dd>
+<example>
+RewriteRule ^/foo$ /bar
+</example>
+<p>Si la directive <directive module="core">DocumentRoot</directive> a
+pour valeur <code>/usr/local/apache2/htdocs</code>, cette règle va faire
+correspondre les requêtes pour <code>http://example.com/foo</code> au
+chemin <code>/usr/local/apache2/htdocs/bar</code>.</p>
+</dd>
+
+<dt>Une URL absolue</dt>
+<dd>
+<example>
+RewriteRule ^/produits/vues$ http://site2.example.com/voirproduits.html [R]
+</example>
+<p>Ceci informe le client qu'il doit effectuer une nouvelle requête vers
+l'URL spécifiée.</p>
+</dd>
+</dl>
+
+<p>La chaîne de <var>Substitution</var> peut aussi contenir des
+<em>références arrières</em> vers des parties du chemin d'URL entrant
+correspondant au <var>Modèle</var>. Considérons ce qui suit :</p>
+<example>
+RewriteRule ^/produits/(.*)/view$ /var/web/produitsdb/$1
+</example>
+<p>La variable <code>$1</code> sera remplacée par tout texte
+correspondant à l'expression située entre les parenthèses dans le
+<var>Modèle</var>. Par exemple, une requête pour
+<code>http://example.com/produits/r14df/vue</code> correspondra au
+chemin <code>/var/web/produitsdb/r14df</code>.</p>
+
+<p>S'il y a plus d'une expression entre parenthèses, elle seront
+accessibles selon leur ordre d'apparition via les variables
+<code>$1</code>, <code>$2</code>, <code>$3</code>, etc...</p>
+
+
+</section>
+
+<section id="flags"><title>Drapeaux de réécriture</title>
+<p>Le comportement d'une règle <directive
+module="mod_rewrite">RewriteRule</directive> peut être modifié par la
+présence d'un ou plusieurs drapeaux en fin de règle. Par exemple, les
+conditions de correspondance d'une règle peuvent être rendues
+insensibles à la casse par la présence du drapeau <code>[NC]</code> :
+</p>
+<example>
+RewriteRule ^puppy.html petitchien.html [NC]
+</example>
+
+<p>Pour une liste des drapeaux disponibles, leurs significations, et des
+exemples, voir le document <a href="flags.html">Drapeaux de
+réécriture</a>.</p>
+
+</section>
+
+
+<section id="rewritecond"><title>Conditions de réécriture</title>
+<p>Il est possible d'utiliser une ou plusieurs directives <directive
+module="mod_rewrite">RewriteCond</directive> pour restreindre les types
+de requêtes auxquelles devra s'appliquer la règle <directive
+module="mod_rewrite">RewriteRule</directive> suivante. Le premier
+argument est une variable décrivant une caractéristique de la requête,
+le second argument est une <a href="#regex">expression rationnelle</a>
+qui doit correspondre à la variable, et un troisième argument optionnel
+est une liste de drapeaux qui modifient la manière dont la
+correspondance est évaluée.</p>
+
+<p class="figure">
+ <img src="../images/syntax_rewritecond.png"
+ alt="Syntaxe de la directive RewriteCond" /><br />
+ <dfn>Figure 3 :</dfn> Syntaxe de la directive RewriteCond
+</p>
+
+
+<p>Par exemple, pour renvoyer toutes les requêtes en provenance d'une
+certaine tranche d'adresses IP vers un autre serveur, vous pouvez
+utiliser :</p>
+<example>
+RewriteCond %{REMOTE_ADDR} ^10\.2\.<br />
+RewriteRule (.*) http://intranet.example.com$1
+</example>
+
+<p>Si vous spécifiez plus d'une directive <directive
+module="mod_rewrite">RewriteCond</directive>, ces directives
+doivent toutes être satisfaites pour que la règle <directive
+module="mod_rewrite">RewriteRule</directive> suivante s'applique. Par exemple,
+pour interdire les requêtes qui contiennent le mot "hack" dans la chaîne
+de requête, sauf si elles contiennent aussi un cookie contenant le mot
+"go", vous pouvez utiliser :</p>
+<example>
+RewriteCond %{QUERY_STRING} hack<br />
+RewriteCond %{HTTP_COOKIE} !go<br />
+RewriteRule .* - [F]
+</example>
+<p>Notez que le point d'exclamation indique une correspondance négative
+; ainsi, la règle n'est appliquée que si le cookie ne contient pas "go"</p>
+
+<p>Les correspondances dans les expressions rationnelles contenues dans
+les directives <directive module="mod_rewrite">RewriteCond</directive>
+peuvent constituer des parties de la chaîne de <var>Substitution</var>
+de la règle <directive module="mod_rewrite">RewriteRule</directive> via
+les variables <code>%1</code>, <code>%2</code>, etc... Par
+exemple, ce qui suit va diriger la requête vers un répertoire différent
+en fonction du nom d'hôte utilisé pour accéder au site :</p>
+<example>
+RewriteCond %{HTTP_HOST} (.*)<br />
+RewriteRule ^/(.*) /sites/%1/$1
+</example>
+<p>Si la requête concernait <code>http://example.com/foo/bar</code>,
+alors <code>%1</code> contiendrait <code>example.com</code> et
+<code>$1</code> contiendrait <code>foo/bar</code>.</p>
+
+
+
+</section>
+
+<section id="rewritemap"><title>Tables de réécriture</title>
+
+<p>La directive <directive module="mod_rewrite">RewriteMap</directive>
+permet en quelque sorte de faire appel à une fonction externe pour
+effectuer la réécriture à votre place. Tout ceci est décrit plus en
+détails dans la <a href="rewritemap.html">Documentation
+supplémentaire sur RewriteMap</a>.</p>
+</section>
+
+<section id="htaccess"><title>Fichiers .htaccess</title>
+
+<p>La réécriture est en général définie au niveau de la configuration du
+serveur principal (en dehors de toute section <directive type="section"
+module="core">Directory</directive>) ou dans une section <directive
+type="section" module="core">VirtualHost</directive>. Il s'agit là de la
+manière la plus simple de mettre en oeuvre la réécriture et nous la
+recommandons. Il est possible, cependant, de mettre en oeuvre la
+réécriture au sein d'une section <directive type="section"
+module="core">Directory</directive> ou d'un fichier <a
+href="../howto/htaccess.html"><code>.htaccess</code></a> ; ce type de
+configuration est cependant plus complexe. Cette technique est appelée
+réécriture par répertoire.</p>
+
+<p>La principale différence avec les réécritures au niveau du serveur réside
+dans le fait que le préfixe du chemin du répertoire contenant le fichier
+<code>.htaccess</code> est supprimé avant la mise en correspondance dans
+la règle <directive module="mod_rewrite">RewriteRule</directive>. De
+plus, on doit utiliser la directive <directive
+module="mod_rewrite">RewriteBase</directive> pour s'assurer que la
+requête est correctement mise en correspondance.</p>
+
+</section>
+
+</manualpage>
+
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- GENERATED FROM XML: DO NOT EDIT -->
+
+<metafile reference="intro.xml">
+ <basename>intro</basename>
+ <path>/rewrite/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant>fr</variant>
+ </variants>
+</metafile>
--- /dev/null
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: proxy.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1
--- /dev/null
+<?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 mod_rewrite for Proxying - 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 mod_rewrite for Proxying</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/rewrite/proxy.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
+how to use the RewriteRule's [P] flag to proxy content to another server.
+A number of recipes are provided that describe common scenarios.</p>
+
+</div>
+<div id="quickview"><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="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="dynamic-proxy" id="dynamic-proxy">Proxying Content with mod_rewrite</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>
+ mod_rewrite provides the [P] flag, which allows URLs to be passed,
+ via mod_proxy, to another server. Two examples are given here. In
+ one example, a URL is passed directly to another server, and served
+ as though it were a local URL. In the other example, we proxy
+ missing content to a back-end server.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>To simply map a URL to another server, we use the [P] flag, as
+ follows:</p>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+RewriteBase /products/<br />
+RewriteRule ^<strong>widget/</strong>(.*)$ <strong>http://product.example.com/widget/</strong>$1 [<strong>P</strong>]<br />
+ProxyPassReverse /products/widget/ http://product.example.com/widget/
+</code></p></div>
+
+ <p>In the second example, we proxy the request only if we can't find
+ the resource locally. This can be very useful when you're migrating
+ from one server to another, and you're not sure if all the content
+ has been migrated yet.</p>
+
+<div class="example"><p><code>
+RewriteCond %{REQUEST_FILENAME} <strong>!-f</strong><br />
+RewriteCond %{REQUEST_FILENAME} <strong>!-d</strong><br />
+RewriteRule ^/(.*) http://<strong>old</strong>.example.com$1 [<strong>P</strong>]<br />
+ProxyPassReverse / http://old.example.com/
+</code></p></div>
+ </dd>
+
+ <dt>Discussion:</dt>
+
+ <dd><p>In each case, we add a <code class="directive"><a href="../mod/mod_proxy.html#proxypassreverse">ProxyPassReverse</a></code> directive to ensure
+ that any redirects issued by the backend are correctly passed on to
+ the client.</p>
+
+ <p>Consider using either <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> or <code class="directive"><a href="../mod/mod_rewrite.html#proxypassmatch">ProxyPassMatch</a></code> whenever possible in
+ preference to mod_rewrite.</p>
+ </dd>
+ </dl>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/proxy.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
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 1059171 $ -->
+
+<!--
+ 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="proxy.xml.meta">
+ <parentdocument href="./">Rewrite</parentdocument>
+
+<title>Using mod_rewrite for Proxying</title>
+
+<summary>
+
+<p>This document supplements the <module>mod_rewrite</module>
+<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
+how to use the RewriteRule's [P] flag to proxy content to another server.
+A number of recipes are provided that describe common scenarios.</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="dynamic-proxy">
+
+ <title>Proxying Content with mod_rewrite</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>
+ mod_rewrite provides the [P] flag, which allows URLs to be passed,
+ via mod_proxy, to another server. Two examples are given here. In
+ one example, a URL is passed directly to another server, and served
+ as though it were a local URL. In the other example, we proxy
+ missing content to a back-end server.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>To simply map a URL to another server, we use the [P] flag, as
+ follows:</p>
+
+<example>
+RewriteEngine on<br />
+RewriteBase /products/<br />
+RewriteRule ^<strong>widget/</strong>(.*)$ <strong>http://product.example.com/widget/</strong>$1 [<strong>P</strong>]<br />
+ProxyPassReverse /products/widget/ http://product.example.com/widget/
+</example>
+
+ <p>In the second example, we proxy the request only if we can't find
+ the resource locally. This can be very useful when you're migrating
+ from one server to another, and you're not sure if all the content
+ has been migrated yet.</p>
+
+<example>
+RewriteCond %{REQUEST_FILENAME} <strong>!-f</strong><br />
+RewriteCond %{REQUEST_FILENAME} <strong>!-d</strong><br />
+RewriteRule ^/(.*) http://<strong>old</strong>.example.com$1 [<strong>P</strong>]<br />
+ProxyPassReverse / http://old.example.com/
+</example>
+ </dd>
+
+ <dt>Discussion:</dt>
+
+ <dd><p>In each case, we add a <directive
+ module="mod_proxy">ProxyPassReverse</directive> directive to ensure
+ that any redirects issued by the backend are correctly passed on to
+ the client.</p>
+
+ <p>Consider using either <directive
+ module="mod_proxy">ProxyPass</directive> or <directive
+ module="mod_rewrite">ProxyPassMatch</directive> whenever possible in
+ preference to mod_rewrite.</p>
+ </dd>
+ </dl>
+
+</section>
+
+</manualpage>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- GENERATED FROM XML: DO NOT EDIT -->
+
+<metafile reference="proxy.xml">
+ <basename>proxy</basename>
+ <path>/rewrite/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
--- /dev/null
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: remapping.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1
--- /dev/null
+<?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>Redirecting and Remapping with mod_rewrite - 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>Redirecting and Remapping with mod_rewrite</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/rewrite/remapping.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
+how you can use <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to redirect and remap
+request. This includes many examples of common uses of mod_rewrite,
+including detailed descriptions of how each works.</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="#old-to-new">From Old to New (internal)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#old-to-new-extern">Rewriting From Old to New (external)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#movehomedirs">Resource Moved to Another Server</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#static-to-dynamic">From Static to Dynamic</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#backward-compatibility">Backward Compatibility for file extension change</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#canonicalhost">Canonical Hostnames</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#multipledirs">Search for pages in more than one directory</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#archive-access-multiplexer">Redirecting to Geographically Distributed Servers</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#browser-dependent-content">Browser Dependent Content</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#canonicalurl">Canonical URLs</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#moveddocroot">Moved <code>DocumentRoot</code></a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#fallback-resource">Fallback Resource</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="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="old-to-new" id="old-to-new">From Old to New (internal)</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>Assume we have recently renamed the page
+ <code>foo.html</code> to <code>bar.html</code> and now want
+ to provide the old URL for backward compatibility. However,
+ we want that users of the old URL even not recognize that
+ the pages was renamed - that is, we don't want the address to
+ change in their browser.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We rewrite the old URL to the new one internally via the
+ following rule:</p>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+RewriteRule ^<strong>/old</strong>\.html$ <strong>/new</strong>.html [PT]
+</code></p></div>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="old-to-new-extern" id="old-to-new-extern">Rewriting From Old to New (external)</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>Assume again that we have recently renamed the page
+ <code>foo.html</code> to <code>bar.html</code> and now want
+ to provide the old URL for backward compatibility. But this
+ time we want that the users of the old URL get hinted to
+ the new one, i.e. their browsers Location field should
+ change, too.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We force a HTTP redirect to the new URL which leads to a
+ change of the browsers and thus the users view:</p>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+RewriteRule ^<strong>/foo</strong>\.html$ <strong>bar</strong>.html [<strong>R</strong>]
+</code></p></div>
+</dd>
+
+<dt>Discussion</dt>
+
+ <dd>
+ <p>In this example, as contrasted to the <a href="#old-to-new-intern">internal</a> example above, we can simply
+ use the Redirect directive. mod_rewrite was used in that earlier
+ example in order to hide the redirect from the client:</p>
+
+ <div class="example"><p><code>
+ Redirect /foo.html /bar.html
+ </code></p></div>
+
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="movehomedirs" id="movehomedirs">Resource Moved to Another Server</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>If a resource has moved to another server, you may wish to have
+ URLs continue to work for a time on the old server while people
+ update their bookmarks.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>You can use <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to redirect these URLs
+ to the new server, but you might also consider using the Redirect
+ or RedirectMatch directive.</p>
+
+<div class="example"><h3>With mod_rewrite</h3><p><code>
+RewriteEngine on<br />
+RewriteRule ^/docs/(.+) http://new.example.com/docs/$1 [R,L]
+</code></p></div>
+
+<div class="example"><h3>With RedirectMatch</h3><p><code>
+RedirectMatch ^/docs/(.*) http://new.example.com/docs/$1
+</code></p></div>
+
+<div class="example"><h3>With Redirect</h3><p><code>
+Redirect /docs/ http://new.example.com/docs/
+</code></p></div>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="static-to-dynamic" id="static-to-dynamic">From Static to Dynamic</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>How can we transform a static page
+ <code>foo.html</code> into a dynamic variant
+ <code>foo.cgi</code> in a seamless way, i.e. without notice
+ by the browser/user.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We just rewrite the URL to the CGI-script and force the
+ handler to be <strong>cgi-script</strong> so that it is
+ executed as a CGI program.
+ This way a request to <code>/~quux/foo.html</code>
+ internally leads to the invocation of
+ <code>/~quux/foo.cgi</code>.</p>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+RewriteBase /~quux/<br />
+RewriteRule ^foo\.<strong>html</strong>$ foo.<strong>cgi</strong> [H=<strong>cgi-script</strong>]
+</code></p></div>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="backward-compatibility" id="backward-compatibility">Backward Compatibility for file extension change</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>How can we make URLs backward compatible (still
+ existing virtually) after migrating <code>document.YYYY</code>
+ to <code>document.XXXX</code>, e.g. after translating a
+ bunch of <code>.html</code> files to <code>.php</code>?</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We rewrite the name to its basename and test for
+ existence of the new extension. If it exists, we take
+ that name, else we rewrite the URL to its original state.</p>
+
+<div class="example"><p><code>
+# backward compatibility ruleset for<br />
+# rewriting document.html to document.php<br />
+# when and only when document.php exists<br />
+<Directory /var/www/htdocs><br />
+<span class="indent">
+RewriteEngine on<br />
+RewriteBase /var/www/htdocs<br />
+<br />
+RewriteCond $1.php -f<br />
+RewriteCond $1.html !-f<br />
+RewriteRule ^(.*).html$ $1.php<br />
+</span>
+</Directory>
+</code></p></div>
+ </dd>
+
+ <dt>Discussion</dt>
+ <dd>
+ <p>This example uses an often-overlooked feature of mod_rewrite,
+ by taking advantage of the order of execution of the ruleset. In
+ particular, mod_rewrite evaluates the left-hand-side of the
+ RewriteRule before it evaluates the RewriteCond directives.
+ Consequently, $1 is already defined by the time the RewriteCond
+ directives are evaluated. This allows us to test for the existence
+ of the original (<code>document.html</code>) and target
+ (<code>document.php</code>) files using the same base filename.</p>
+
+ <p>This ruleset is designed to use in a per-directory context (In a
+ <Directory> block or in a .htaccess file), so that the
+ <code>-f</code> checks are looking at the correct directory path.
+ You may need to set a <code class="directive"><a href="../mod/mod_rewite.html#rewritebase">RewriteBase</a></code> directive to specify the
+ directory base that you're working in.</p>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="canonicalhost" id="canonicalhost">Canonical Hostnames</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>The goal of this rule is to force the use of a particular
+ hostname, in preference to other hostnames which may be used to
+ reach the same site. For example, if you wish to force the use
+ of <strong>www.example.com</strong> instead of
+ <strong>example.com</strong>, you might use a variant of the
+ following recipe.</dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+
+<p>The very best way to solve this doesn't involve mod_rewrite at all,
+but rather uses the <code class="directive"><a href="../mod/alias.html#redirect">Redirect</a></code>
+directive placed in a virtual host for the non-canonical
+hostname(s).</p>
+
+<div class="example"><p><code>
+<VirtualHost *:80><br />
+<span class="indent">
+ ServerName undesired.example.com<br />
+ ServerAlias example.com notthis.example.com<br />
+<br />
+ Redirect / http://www.example.com/<br />
+</span>
+</VirtualHost><br />
+<br />
+<VirtualHost *:80><br />
+<span class="indent">
+ ServerName www.example.com<br />
+</span>
+</VirtualHost>
+</code></p></div>
+
+<p>You can alternatively accomplish this using the
+<code class="directive"><a href="../mod/core.html#if"><If></a></code>
+directive:</p>
+
+<div class="example"><p><code>
+<If "%{HTTP_HOST} != 'www.example.com'"><br />
+<span class="indent">
+Redirect / http://www.example.com/
+</span>
+</If>
+</code></p></div>
+
+<p>Or, for example, to redirect a portion of your site to HTTPS, you
+might do the following:</p>
+
+<div class="example"><p><code>
+<If "%{SERVER_PROTOCOL} != 'HTTPS'"><br />
+<span class="indent">
+Redirect /admin/ https://www.example.com/admin/
+</span>
+</If>
+</code></p></div>
+
+<p>If, for whatever reason, you still want to use <code>mod_rewrite</code>
+- if, for example, you need this to work with a larger set of RewriteRules -
+you might use one of the recipes below.</p>
+
+<p>For sites running on a port other than 80:</p>
+<div class="example"><p><code>
+RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]<br />
+RewriteCond %{HTTP_HOST} !^$<br />
+RewriteCond %{SERVER_PORT} !^80$<br />
+RewriteRule ^/?(.*) http://www.example.com:%{SERVER_PORT}/$1 [L,R,NE]
+</code></p></div>
+
+<p>And for a site running on port 80</p>
+<div class="example"><p><code>
+RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]<br />
+RewriteCond %{HTTP_HOST} !^$<br />
+RewriteRule ^/?(.*) http://www.example.com/$1 [L,R,NE]
+</code></p></div>
+
+ <p>
+ If you wanted to do this generically for all domain names - that
+ is, if you want to redirect <strong>example.com</strong> to
+ <strong>www.example.com</strong> for all possible values of
+ <strong>example.com</strong>, you could use the following
+ recipe:</p>
+
+<div class="example"><p><code>
+RewriteCond %{HTTP_HOST} !^www\. [NC]<br />
+RewriteCond %{HTTP_HOST} !^$<br />
+RewriteRule ^/?(.*) http://www.%{HTTP_HOST}/$1 [L,R,NE]
+</code></p></div>
+
+ <p>These rulesets will work either in your main server configuration
+ file, or in a <code>.htaccess</code> file placed in the <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> of the server.</p>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="multipledirs" id="multipledirs">Search for pages in more than one directory</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>A particular resource might exist in one of several places, and
+ we want to look in those places for the resource when it is
+ requested. Perhaps we've recently rearranged our directory
+ structure, dividing content into several locations.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>The following ruleset searches in two directories to find the
+ resource, and, if not finding it in either place, will attempt to
+ just serve it out of the location requested.</p>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+<br />
+# first try to find it in dir1/...<br />
+# ...and if found stop and be happy:<br />
+RewriteCond %{DOCUMENT_ROOT}/<strong>dir1</strong>/%{REQUEST_URI} -f<br />
+RewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir1</strong>/$1 [L]<br />
+<br />
+# second try to find it in dir2/...<br />
+# ...and if found stop and be happy:<br />
+RewriteCond %{DOCUMENT_ROOT}/<strong>dir2</strong>/%{REQUEST_URI} -f<br />
+RewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir2</strong>/$1 [L]<br />
+<br />
+# else go on for other Alias or ScriptAlias directives,<br />
+# etc.<br />
+RewriteRule ^ - [PT]
+</code></p></div>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="archive-access-multiplexer" id="archive-access-multiplexer">Redirecting to Geographically Distributed Servers</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We have numerous mirrors of our website, and want to redirect
+ people to the one that is located in the country where they are
+ located.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>Looking at the hostname of the requesting client, we determine
+ which country they are coming from. If we can't do a lookup on their
+ IP address, we fall back to a default server.</p>
+ <p>We'll use a <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code>
+ directive to build a list of servers that we wish to use.</p>
+
+<div class="example"><p><code>
+HostnameLookups on<br />
+RewriteEngine on<br />
+RewriteMap multiplex txt:/path/to/map.mirrors<br />
+RewriteCond %{REMOTE_HOST} ([a-z]+)$ [NC]<br />
+RewriteRule ^/(.*)$ ${multiplex:<strong>%1</strong>|http://www.example.com/}$1 [R,L]
+</code></p></div>
+
+<div class="example"><p><code>
+## map.mirrors -- Multiplexing Map<br />
+<br />
+de http://www.example.de/<br />
+uk http://www.example.uk/<br />
+com http://www.example.com/<br />
+##EOF##
+</code></p></div>
+ </dd>
+
+ <dt>Discussion</dt>
+ <dd>
+ <div class="warning">This ruleset relies on
+ <code class="directive"><a href="../mod/core.html#hostnamelookups">HostNameLookups</a></code>
+ being set <code>on</code>, which can be
+ a significant performance hit.</div>
+
+ <p>The <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>
+ directive captures the last portion of the hostname of the
+ requesting client - the country code - and the following RewriteRule
+ uses that value to look up the appropriate mirror host in the map
+ file.</p>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="browser-dependent-content" id="browser-dependent-content">Browser Dependent Content</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We wish to provide different content based on the browser, or
+ user-agent, which is requesting the content.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We have to decide, based on the HTTP header "User-Agent",
+ which content to serve. The following config
+ does the following: If the HTTP header "User-Agent"
+ contains "Mozilla/3", the page <code>foo.html</code>
+ is rewritten to <code>foo.NS.html</code> and the
+ rewriting stops. If the browser is "Lynx" or "Mozilla" of
+ version 1 or 2, the URL becomes <code>foo.20.html</code>.
+ All other browsers receive page <code>foo.32.html</code>.
+ This is done with the following ruleset:</p>
+
+<div class="example"><p><code>
+RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/3</strong>.*<br />
+RewriteRule ^foo\.html$ foo.<strong>NS</strong>.html [<strong>L</strong>]<br />
+<br />
+RewriteCond %{HTTP_USER_AGENT} ^<strong>Lynx/</strong>.* [OR]<br />
+RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/[12]</strong>.*<br />
+RewriteRule ^foo\.html$ foo.<strong>20</strong>.html [<strong>L</strong>]<br />
+<br />
+RewriteRule ^foo\.html$ foo.<strong>32</strong>.html [<strong>L</strong>]
+</code></p></div>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="canonicalurl" id="canonicalurl">Canonical URLs</a></h2>
+
+
+
+<dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>On some webservers there is more than one URL for a
+ resource. Usually there are canonical URLs (which are be
+ actually used and distributed) and those which are just
+ shortcuts, internal ones, and so on. Independent of which URL the
+ user supplied with the request, they should finally see the
+ canonical one in their browser address bar.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We do an external HTTP redirect for all non-canonical
+ URLs to fix them in the location view of the Browser and
+ for all subsequent requests. In the example ruleset below
+ we replace <code>/puppies</code> and <code>/canines</code>
+ by the canonical <code>/dogs</code>.</p>
+
+<div class="example"><p><code>
+RewriteRule ^/(puppies|canines)/(.*) /dogs/$2 [R]
+</code></p></div>
+ </dd>
+
+ <dt>Discussion:</dt>
+ <dd>
+ This should really be accomplished with Redirect or RedirectMatch
+ directives:
+
+ <div class="example"><p><code>
+ RedirectMatch ^/(puppies|canines)/(.*) /dogs/$2
+ </code></p></div>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="moveddocroot" id="moveddocroot">Moved <code>DocumentRoot</code></a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+<p>Usually the <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>
+of the webserver directly relates to the URL "<code>/</code>".
+But often this data is not really of top-level priority. For example,
+you may wish for visitors, on first entering a site, to go to a
+particular subdirectory <code>/about/</code>. This may be accomplished
+using the following ruleset:</p>
+</dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We redirect the URL <code>/</code> to
+ <code>/about/</code>:
+ </p>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+RewriteRule <strong>^/$</strong> /about/ [<strong>R</strong>]
+</code></p></div>
+
+<p>Note that this can also be handled using the <code class="directive"><a href="../mod/mod_alias.html#redirectmatch">RedirectMatch</a></code> directive:</p>
+
+<div class="example"><p><code>
+RedirectMatch ^/$ http://example.com/about/
+</code></p></div>
+
+<p>Note also that the example rewrites only the root URL. That is, it
+rewrites a request for <code>http://example.com/</code>, but not a
+request for <code>http://example.com/page.html</code>. If you have in
+fact changed your document root - that is, if <strong>all</strong> of
+your content is in fact in that subdirectory, it is greatly preferable
+to simply change your <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>
+directive, or move all of the content up one directory,
+rather than rewriting URLs.</p>
+</dd>
+</dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="fallback-resource" id="fallback-resource">Fallback Resource</a></h2>
+
+
+<dl>
+<dt>Description:</dt>
+<dd>You want a single resource (say, a certain file, like index.php) to
+handle all requests that come to a particular directory, except those
+that should go to an existing resource such as an image, or a css file.</dd>
+
+<dt>Solution:</dt>
+<dd>
+<p>As of version 2.2.16, you should use the <code class="directive"><a href="../mod/mod_dir.html#fallbackresource">FallbackResource</a></code> directive for this:</p>
+
+<div class="example"><p><code>
+<Directory /var/www/my_blog><br />
+<span class="indent">
+ FallbackResource index.php<br />
+</span>
+</Directory>
+</code></p></div>
+
+<p>However, in earlier versions of Apache, or if your needs are more
+complicated than this, you can use a variation of the following rewrite
+set to accomplish the same thing:</p>
+
+<div class="example"><p><code>
+<Directory /var/www/my_blog><br />
+<span class="indent">
+ RewriteBase /my_blog<br />
+<br />
+ RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-f<br />
+ RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-d<br />
+ RewriteRule ^ index.php [PT]<br />
+</span>
+</Directory>
+</code></p></div>
+
+<p>If, on the other hand, you wish to pass the requested URI as a query
+string argument to index.php, you can replace that RewriteRule with:</p>
+
+<div class="example"><p><code>
+ RewriteRule (.*) index.php?$1 [PT,QSA]
+</code></p></div>
+
+<p>Note that these rulesets can be uses in a <code>.htaccess</code>
+file, as well as in a <Directory> block.</p>
+
+</dd>
+
+</dl>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/remapping.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
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 1059174 $ -->
+
+<!--
+ 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="remapping.xml.meta">
+ <parentdocument href="./">Rewrite</parentdocument>
+
+<title>Redirecting and Remapping with mod_rewrite</title>
+
+<summary>
+
+<p>This document supplements the <module>mod_rewrite</module>
+<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
+how you can use <module>mod_rewrite</module> to redirect and remap
+request. This includes many examples of common uses of mod_rewrite,
+including detailed descriptions of how each works.</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="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="old-to-new">
+
+ <title>From Old to New (internal)</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>Assume we have recently renamed the page
+ <code>foo.html</code> to <code>bar.html</code> and now want
+ to provide the old URL for backward compatibility. However,
+ we want that users of the old URL even not recognize that
+ the pages was renamed - that is, we don't want the address to
+ change in their browser.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We rewrite the old URL to the new one internally via the
+ following rule:</p>
+
+<example>
+RewriteEngine on<br />
+RewriteRule ^<strong>/old</strong>\.html$ <strong>/new</strong>.html [PT]
+</example>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="old-to-new-extern">
+
+ <title>Rewriting From Old to New (external)</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>Assume again that we have recently renamed the page
+ <code>foo.html</code> to <code>bar.html</code> and now want
+ to provide the old URL for backward compatibility. But this
+ time we want that the users of the old URL get hinted to
+ the new one, i.e. their browsers Location field should
+ change, too.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We force a HTTP redirect to the new URL which leads to a
+ change of the browsers and thus the users view:</p>
+
+<example>
+RewriteEngine on<br />
+RewriteRule ^<strong>/foo</strong>\.html$ <strong>bar</strong>.html [<strong>R</strong>]
+</example>
+</dd>
+
+<dt>Discussion</dt>
+
+ <dd>
+ <p>In this example, as contrasted to the <a
+ href="#old-to-new-intern">internal</a> example above, we can simply
+ use the Redirect directive. mod_rewrite was used in that earlier
+ example in order to hide the redirect from the client:</p>
+
+ <example>
+ Redirect /foo.html /bar.html
+ </example>
+
+ </dd>
+ </dl>
+
+</section>
+
+<section id="movehomedirs">
+
+ <title>Resource Moved to Another Server</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>If a resource has moved to another server, you may wish to have
+ URLs continue to work for a time on the old server while people
+ update their bookmarks.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>You can use <module>mod_rewrite</module> to redirect these URLs
+ to the new server, but you might also consider using the Redirect
+ or RedirectMatch directive.</p>
+
+<example><title>With mod_rewrite</title>
+RewriteEngine on<br />
+RewriteRule ^/docs/(.+) http://new.example.com/docs/$1 [R,L]
+</example>
+
+<example><title>With RedirectMatch</title>
+RedirectMatch ^/docs/(.*) http://new.example.com/docs/$1
+</example>
+
+<example><title>With Redirect</title>
+Redirect /docs/ http://new.example.com/docs/
+</example>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="static-to-dynamic">
+
+ <title>From Static to Dynamic</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>How can we transform a static page
+ <code>foo.html</code> into a dynamic variant
+ <code>foo.cgi</code> in a seamless way, i.e. without notice
+ by the browser/user.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We just rewrite the URL to the CGI-script and force the
+ handler to be <strong>cgi-script</strong> so that it is
+ executed as a CGI program.
+ This way a request to <code>/~quux/foo.html</code>
+ internally leads to the invocation of
+ <code>/~quux/foo.cgi</code>.</p>
+
+<example>
+RewriteEngine on<br />
+RewriteBase /~quux/<br />
+RewriteRule ^foo\.<strong>html</strong>$ foo.<strong>cgi</strong> [H=<strong>cgi-script</strong>]
+</example>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="backward-compatibility">
+
+ <title>Backward Compatibility for file extension change</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>How can we make URLs backward compatible (still
+ existing virtually) after migrating <code>document.YYYY</code>
+ to <code>document.XXXX</code>, e.g. after translating a
+ bunch of <code>.html</code> files to <code>.php</code>?</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We rewrite the name to its basename and test for
+ existence of the new extension. If it exists, we take
+ that name, else we rewrite the URL to its original state.</p>
+
+<example>
+# backward compatibility ruleset for<br />
+# rewriting document.html to document.php<br />
+# when and only when document.php exists<br />
+<Directory /var/www/htdocs><br />
+<indent>
+RewriteEngine on<br />
+RewriteBase /var/www/htdocs<br />
+<br />
+RewriteCond $1.php -f<br />
+RewriteCond $1.html !-f<br />
+RewriteRule ^(.*).html$ $1.php<br />
+</indent>
+</Directory>
+</example>
+ </dd>
+
+ <dt>Discussion</dt>
+ <dd>
+ <p>This example uses an often-overlooked feature of mod_rewrite,
+ by taking advantage of the order of execution of the ruleset. In
+ particular, mod_rewrite evaluates the left-hand-side of the
+ RewriteRule before it evaluates the RewriteCond directives.
+ Consequently, $1 is already defined by the time the RewriteCond
+ directives are evaluated. This allows us to test for the existence
+ of the original (<code>document.html</code>) and target
+ (<code>document.php</code>) files using the same base filename.</p>
+
+ <p>This ruleset is designed to use in a per-directory context (In a
+ <Directory> block or in a .htaccess file), so that the
+ <code>-f</code> checks are looking at the correct directory path.
+ You may need to set a <directive
+ module="mod_rewite">RewriteBase</directive> directive to specify the
+ directory base that you're working in.</p>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="canonicalhost">
+
+<title>Canonical Hostnames</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>The goal of this rule is to force the use of a particular
+ hostname, in preference to other hostnames which may be used to
+ reach the same site. For example, if you wish to force the use
+ of <strong>www.example.com</strong> instead of
+ <strong>example.com</strong>, you might use a variant of the
+ following recipe.</dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+
+<p>The very best way to solve this doesn't involve mod_rewrite at all,
+but rather uses the <directive module="alias">Redirect</directive>
+directive placed in a virtual host for the non-canonical
+hostname(s).</p>
+
+<example>
+<VirtualHost *:80><br />
+<indent>
+ ServerName undesired.example.com<br />
+ ServerAlias example.com notthis.example.com<br />
+<br />
+ Redirect / http://www.example.com/<br />
+</indent>
+</VirtualHost><br />
+<br />
+<VirtualHost *:80><br />
+<indent>
+ ServerName www.example.com<br />
+</indent>
+</VirtualHost>
+</example>
+
+<p>You can alternatively accomplish this using the
+<directive module="core" type="section">If</directive>
+directive:</p>
+
+<example>
+<If "%{HTTP_HOST} != 'www.example.com'"><br />
+<indent>
+Redirect / http://www.example.com/
+</indent>
+</If>
+</example>
+
+<p>Or, for example, to redirect a portion of your site to HTTPS, you
+might do the following:</p>
+
+<example>
+<If "%{SERVER_PROTOCOL} != 'HTTPS'"><br />
+<indent>
+Redirect /admin/ https://www.example.com/admin/
+</indent>
+</If>
+</example>
+
+<p>If, for whatever reason, you still want to use <code>mod_rewrite</code>
+- if, for example, you need this to work with a larger set of RewriteRules -
+you might use one of the recipes below.</p>
+
+<p>For sites running on a port other than 80:</p>
+<example>
+RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]<br />
+RewriteCond %{HTTP_HOST} !^$<br />
+RewriteCond %{SERVER_PORT} !^80$<br />
+RewriteRule ^/?(.*) http://www.example.com:%{SERVER_PORT}/$1 [L,R,NE]
+</example>
+
+<p>And for a site running on port 80</p>
+<example>
+RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]<br />
+RewriteCond %{HTTP_HOST} !^$<br />
+RewriteRule ^/?(.*) http://www.example.com/$1 [L,R,NE]
+</example>
+
+ <p>
+ If you wanted to do this generically for all domain names - that
+ is, if you want to redirect <strong>example.com</strong> to
+ <strong>www.example.com</strong> for all possible values of
+ <strong>example.com</strong>, you could use the following
+ recipe:</p>
+
+<example>
+RewriteCond %{HTTP_HOST} !^www\. [NC]<br />
+RewriteCond %{HTTP_HOST} !^$<br />
+RewriteRule ^/?(.*) http://www.%{HTTP_HOST}/$1 [L,R,NE]
+</example>
+
+ <p>These rulesets will work either in your main server configuration
+ file, or in a <code>.htaccess</code> file placed in the <directive
+ module="core">DocumentRoot</directive> of the server.</p>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="multipledirs">
+
+ <title>Search for pages in more than one directory</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>A particular resource might exist in one of several places, and
+ we want to look in those places for the resource when it is
+ requested. Perhaps we've recently rearranged our directory
+ structure, dividing content into several locations.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>The following ruleset searches in two directories to find the
+ resource, and, if not finding it in either place, will attempt to
+ just serve it out of the location requested.</p>
+
+<example>
+RewriteEngine on<br />
+<br />
+# first try to find it in dir1/...<br />
+# ...and if found stop and be happy:<br />
+RewriteCond %{DOCUMENT_ROOT}/<strong>dir1</strong>/%{REQUEST_URI} -f<br />
+RewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir1</strong>/$1 [L]<br />
+<br />
+# second try to find it in dir2/...<br />
+# ...and if found stop and be happy:<br />
+RewriteCond %{DOCUMENT_ROOT}/<strong>dir2</strong>/%{REQUEST_URI} -f<br />
+RewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir2</strong>/$1 [L]<br />
+<br />
+# else go on for other Alias or ScriptAlias directives,<br />
+# etc.<br />
+RewriteRule ^ - [PT]
+</example>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="archive-access-multiplexer">
+
+ <title>Redirecting to Geographically Distributed Servers</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We have numerous mirrors of our website, and want to redirect
+ people to the one that is located in the country where they are
+ located.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>Looking at the hostname of the requesting client, we determine
+ which country they are coming from. If we can't do a lookup on their
+ IP address, we fall back to a default server.</p>
+ <p>We'll use a <directive module="mod_rewrite">RewriteMap</directive>
+ directive to build a list of servers that we wish to use.</p>
+
+<example>
+HostnameLookups on<br />
+RewriteEngine on<br />
+RewriteMap multiplex txt:/path/to/map.mirrors<br />
+RewriteCond %{REMOTE_HOST} ([a-z]+)$ [NC]<br />
+RewriteRule ^/(.*)$ ${multiplex:<strong>%1</strong>|http://www.example.com/}$1 [R,L]
+</example>
+
+<example>
+## map.mirrors -- Multiplexing Map<br />
+<br />
+de http://www.example.de/<br />
+uk http://www.example.uk/<br />
+com http://www.example.com/<br />
+##EOF##
+</example>
+ </dd>
+
+ <dt>Discussion</dt>
+ <dd>
+ <note type="warning">This ruleset relies on
+ <directive module="core">HostNameLookups</directive>
+ being set <code>on</code>, which can be
+ a significant performance hit.</note>
+
+ <p>The <directive module="mod_rewrite">RewriteCond</directive>
+ directive captures the last portion of the hostname of the
+ requesting client - the country code - and the following RewriteRule
+ uses that value to look up the appropriate mirror host in the map
+ file.</p>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="browser-dependent-content">
+
+ <title>Browser Dependent Content</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We wish to provide different content based on the browser, or
+ user-agent, which is requesting the content.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We have to decide, based on the HTTP header "User-Agent",
+ which content to serve. The following config
+ does the following: If the HTTP header "User-Agent"
+ contains "Mozilla/3", the page <code>foo.html</code>
+ is rewritten to <code>foo.NS.html</code> and the
+ rewriting stops. If the browser is "Lynx" or "Mozilla" of
+ version 1 or 2, the URL becomes <code>foo.20.html</code>.
+ All other browsers receive page <code>foo.32.html</code>.
+ This is done with the following ruleset:</p>
+
+<example>
+RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/3</strong>.*<br />
+RewriteRule ^foo\.html$ foo.<strong>NS</strong>.html [<strong>L</strong>]<br />
+<br />
+RewriteCond %{HTTP_USER_AGENT} ^<strong>Lynx/</strong>.* [OR]<br />
+RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/[12]</strong>.*<br />
+RewriteRule ^foo\.html$ foo.<strong>20</strong>.html [<strong>L</strong>]<br />
+<br />
+RewriteRule ^foo\.html$ foo.<strong>32</strong>.html [<strong>L</strong>]
+</example>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="canonicalurl">
+
+<title>Canonical URLs</title>
+
+<dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>On some webservers there is more than one URL for a
+ resource. Usually there are canonical URLs (which are be
+ actually used and distributed) and those which are just
+ shortcuts, internal ones, and so on. Independent of which URL the
+ user supplied with the request, they should finally see the
+ canonical one in their browser address bar.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We do an external HTTP redirect for all non-canonical
+ URLs to fix them in the location view of the Browser and
+ for all subsequent requests. In the example ruleset below
+ we replace <code>/puppies</code> and <code>/canines</code>
+ by the canonical <code>/dogs</code>.</p>
+
+<example>
+RewriteRule ^/(puppies|canines)/(.*) /dogs/$2 [R]
+</example>
+ </dd>
+
+ <dt>Discussion:</dt>
+ <dd>
+ This should really be accomplished with Redirect or RedirectMatch
+ directives:
+
+ <example>
+ RedirectMatch ^/(puppies|canines)/(.*) /dogs/$2
+ </example>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="moveddocroot">
+
+ <title>Moved <code>DocumentRoot</code></title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+<p>Usually the <directive module="core">DocumentRoot</directive>
+of the webserver directly relates to the URL "<code>/</code>".
+But often this data is not really of top-level priority. For example,
+you may wish for visitors, on first entering a site, to go to a
+particular subdirectory <code>/about/</code>. This may be accomplished
+using the following ruleset:</p>
+</dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+ <p>We redirect the URL <code>/</code> to
+ <code>/about/</code>:
+ </p>
+
+<example>
+RewriteEngine on<br />
+RewriteRule <strong>^/$</strong> /about/ [<strong>R</strong>]
+</example>
+
+<p>Note that this can also be handled using the <directive
+module="mod_alias">RedirectMatch</directive> directive:</p>
+
+<example>
+RedirectMatch ^/$ http://example.com/about/
+</example>
+
+<p>Note also that the example rewrites only the root URL. That is, it
+rewrites a request for <code>http://example.com/</code>, but not a
+request for <code>http://example.com/page.html</code>. If you have in
+fact changed your document root - that is, if <strong>all</strong> of
+your content is in fact in that subdirectory, it is greatly preferable
+to simply change your <directive module="core">DocumentRoot</directive>
+directive, or move all of the content up one directory,
+rather than rewriting URLs.</p>
+</dd>
+</dl>
+
+</section>
+
+<section id="fallback-resource">
+<title>Fallback Resource</title>
+
+<dl>
+<dt>Description:</dt>
+<dd>You want a single resource (say, a certain file, like index.php) to
+handle all requests that come to a particular directory, except those
+that should go to an existing resource such as an image, or a css file.</dd>
+
+<dt>Solution:</dt>
+<dd>
+<p>As of version 2.2.16, you should use the <directive
+module="mod_dir">FallbackResource</directive> directive for this:</p>
+
+<example>
+<Directory /var/www/my_blog><br />
+<indent>
+ FallbackResource index.php<br />
+</indent>
+</Directory>
+</example>
+
+<p>However, in earlier versions of Apache, or if your needs are more
+complicated than this, you can use a variation of the following rewrite
+set to accomplish the same thing:</p>
+
+<example>
+<Directory /var/www/my_blog><br />
+<indent>
+ RewriteBase /my_blog<br />
+<br />
+ RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-f<br />
+ RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-d<br />
+ RewriteRule ^ index.php [PT]<br />
+</indent>
+</Directory>
+</example>
+
+<p>If, on the other hand, you wish to pass the requested URI as a query
+string argument to index.php, you can replace that RewriteRule with:</p>
+
+<example>
+ RewriteRule (.*) index.php?$1 [PT,QSA]
+</example>
+
+<p>Note that these rulesets can be uses in a <code>.htaccess</code>
+file, as well as in a <Directory> block.</p>
+
+</dd>
+
+</dl>
+
+</section>
+
+</manualpage>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- GENERATED FROM XML: DO NOT EDIT -->
+
+<metafile reference="remapping.xml">
+ <basename>remapping</basename>
+ <path>/rewrite/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
+++ /dev/null
-<?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 Flags - 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 Flags</h1>
-<div class="toplang">
-<p><span>Available Languages: </span><a href="../en/rewrite/rewrite_flags.html" title="English"> en </a></p>
-</div>
-
-<p>This document discusses the flags which are available to the
-<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive,
-providing detailed explanations and examples. This is not necessarily
-a comprehensive list of all flags available, so be sure to also
-consult the reference documentation.</p>
-</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="#flags">The flags</a></li>
-</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="rewrite_tech.html">Technical details</a></li><li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li><li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide -
-advanced useful examples</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><code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s can have
-their behavior modified by one or more flags. Flags are included in
-square brackets at the end of the rule, and multiple flags are separated
-by commas.</p>
-<div class="example"><p><code>
-RewriteRule pattern target [Flag1,Flag2,Flag3]
-</code></p></div>
-
-<p>The flags all have a short form, such as <code>CO</code>, as well as
-a longer form, such as <code>cookie</code>. Some flags take one or more
-arguments. Flags are not case sensitive.</p>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="flags" id="flags">The flags</a></h2>
-
-<p>Each flag has a long and short form. While it is most common to use
-the short form, it is recommended that you familiarize yourself with the
-long form, so that you remember what each flag is supposed to do.</p>
-
-<p>Presented here are each of the available flags, along with an example
-of how you might use them.</p>
-
-<h3><a name="flag_c" id="flag_c">C|chain</a></h3>
-<p>The [C] or [chain] flag indicates that the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is chained to the next
-rule. That is, if the rule matches, then it is processed as usual and
-control moves on to the next rule. However, if it does not match, then
-the next rule, and any other rules that are chained together, will be
-skipped.</p>
-
-
-
-<h3><a name="flag_co" id="flag_co">CO|cookie</a></h3>
-<p>The [CO], or [cookie] flag, allows you to set a cookie when a
-particular <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>
-matches. The argument consists of three required fields and two optional
-fields.</p>
-<p>You must declare a name and value for the cookie to be set, and the
-domain for which you wish the cookie to be valid. You may optionally set
-the lifetime of the cookie, and the path for which it should be
-returned.</p>
-<p>By default, the lifetime of the cookie is the current browser
-session.</p>
-<p>By default, the path for which the cookie will be valid is "/" - that
-is, the entire website.</p>
-<p>Several examples are offered here:</p>
-
-<div class="example"><p><code>
-RewriteEngine On<br />
-RewriteRule ^/index.html - [CO=frontdoor:yes:.apache.org:1440:/]
-</code></p></div>
-
-<p>This rule doesn't rewrite the request (the "-" rewrite target tells
-mod_rewrite to pass the request through unchanged) but sets a cookie
-called 'frontdoor' to a value of 'yes'. The cookie is valid for any host
-in the <code>.apache.org</code> domain. It will be set to expire in 1440
-minutes (24 hours) and will be returned for all URIs.</p>
-
-
-
-<h3><a name="flag_e" id="flag_e">E|env</a></h3>
-<p>With the [E], or [env] flag, you can set the value of an environment
-variable. Note that some environment variables may be set after the rule
-is run, thus unsetting what you have set. See <a href="../env.html">the
-Environment Variables document</a> for more details on how Environment
-variables work.</p>
-
-<p>The full syntax for this flag is:</p>
-
-<div class="example"><p><code>
-[E=VAR:VAL]
-[E=!VAR]
-</code></p></div>
-
-<p><code>VAL</code> may contain backreferences (<code>$N</code> or
-<code>%N</code>) which will be expanded.</p>
-
-<p>Using the short form</p>
-
-<div class="example"><p><code>
-[E=VAR]
-</code></p></div>
-
-<p>you can set the environment variable named <code>VAR</code> to an
-empty value.</p>
-
-<p>The form</p>
-
-<div class="example"><p><code>
-[E=!VAR]
-</code></p></div>
-
-<p>allows to unset a previously set environment variable named
-<code>VAR</code>.</p>
-
-<p>Environment variables can then be used in a variety of
-contexts, including CGI programs, other RewriteRule directives, or
-CustomLog directives.</p>
-
-<p>The following example sets an environment variable called 'image' to a
-value of '1' if the requested URI is an image file. Then, that
-environment variable is used to exclude those requests from the access
-log.</p>
-
-<div class="example"><p><code>
-RewriteRule \.(png|gif|jpg) - [E=image:1]<br />
-CustomLog logs/access_log combined env=!image
-</code></p></div>
-
-<p>Note that this same effect can be obtained using <code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code>. This technique is offered as
-an example, not as a recommendation.</p>
-
-
-<h3><a name="flag_f" id="flag_f">F|forbidden</a></h3>
-<p>Using the [F] flag causes Apache to return a 403 Forbidden status
-code to the client. While the same behavior can be accomplished using
-the <code class="directive"><a href="../mod/mod_access.html#deny">Deny</a></code> directive, this
-allows more flexibility in assigning a Forbidden status.</p>
-
-<p>The following rule will forbid <code>.exe</code> files from being
-downloaded from your server.</p>
-
-<div class="example"><p><code>
-RewriteRule \.exe - [F]
-</code></p></div>
-
-<p>This example uses the "-" syntax for the rewrite target, which means
-that the requested URI is not modified. There's no reason to rewrite to
-another URI, if you're going to forbid the request.</p>
-
-
-
-<h3><a name="flag_g" id="flag_g">G|gone</a></h3>
-<p>The [G] flag forces Apache to return a 410 Gone status with the
-response. This indicates that a resource used to be available, but is no
-longer available.</p>
-
-<p>As with the [F] flag, you will typically use the "-" syntax for the
-rewrite target when using the [G] flag:</p>
-
-<div class="example"><p><code>
-RewriteRule oldproduct - [G,NC]
-</code></p></div>
-
-
-<h3><a name="flag_h" id="flag_h">H|handler</a></h3>
-<p>Forces the resulting request to be handled with the specified
-handler. For example, one might use this to force all files without a
-file extension to be parsed by the php handler:</p>
-
-<div class="example"><p><code>
-RewriteRule !\. - [H=application/x-httpd-php]
-</code></p></div>
-
-<p>
-The regular expression above - <code>!\.</code> - will match any request
-that does not contain the literal <code>.</code> character.
-</p>
-
-
-<h3><a name="flag_l" id="flag_l">L|last</a></h3>
-<p>The [L] flag causes <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to stop processing
-the rule set. In most contexts, this means that if the rule matches, no
-further rules will be processed.</p>
-
-<p>If you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> in either
-<code>.htaccess</code> files or in
-<code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> sections,
-it is important to have some understanding of how the rules are
-processed. The simplified form of this is that once the rules have been
-processed, the rewritten request is handed back to the URL parsing
-engine to do what it may with it. It is possible that as the rewritten
-request is handled, the <code>.htaccess</code> file or
-<code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section
-may be encountered again, and thus the ruleset may be run again from the
-start. Most commonly this will happen if one of the rules causes a
-redirect - either internal or external - causing the request process to
-start over.</p>
-
-<p>It is therefore important, if you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives in one of these
-context that you take explicit steps to avoid rules looping, and not
-count solely on the [L] flag to terminate execution of a series of
-rules, as shown below.</p>
-
-<p>The example given here will rewrite any request to
-<code>index.php</code>, giving the original request as a query string
-argument to <code>index.php</code>, however, if the request is already
-for <code>index.php</code>, this rule will be skipped.</p>
-
-<div class="example"><p><code>
-RewriteCond %{REQUEST_URI} !index\.php<br />
-RewriteRule ^(.*) index.php?req=$1 [L]
-</code></p></div>
-
-
-<h3><a name="flag_n" id="flag_n">N|next</a></h3>
-<p>
-The [N] flag causes the ruleset to start over again from the top. Use
-with extreme caution, as it may result in loop.
-</p>
-<p>
-The [Next] flag could be used, for example, if you wished to replace a
-certain string or letter repeatedly in a request. The example shown here
-will replace A with B everywhere in a request, and will continue doing
-so until there are no more As to be replaced.
-</p>
-
-<div class="example"><p><code>
-RewriteRule (.*)A(.*) $1B$2 [N]
-</code></p></div>
-
-<p>You can think of this as a <code>while</code> loop: While this
-pattern still matches, perform this substitution.</p>
-
-
-
-<h3><a name="flag_nc" id="flag_nc">NC|nocase</a></h3>
-<p>Use of the [NC] flag causes the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be matched in a
-case-insensitive manner. That is, it doesn't care whether letters appear
-as upper-case or lower-case in the matched URI.</p>
-
-<p>In the example below, any request for an image file will be proxied
-to your dedicated image server. The match is case-insensitive, so that
-<code>.jpg</code> and <code>.JPG</code> files are both acceptable, for
-example.</p>
-
-<div class="example"><p><code>
-RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC]
-</code></p></div>
-
-
-<h3><a name="flag_ne" id="flag_ne">NE|noescape</a></h3>
-<p>By default, special characters, such as <code>&</code> and
-<code>?</code>, for example, will be converted to their hexcode
-equivalent. Using the [NE] flag prevents that from happening.
-</p>
-
-<div class="example"><p><code>
-RewriteRule ^/anchor/(.+) /bigpage.html#$1 [NE,R]
-</code></p></div>
-
-<p>
-The above example will redirect <code>/anchor/xyz</code> to
-<code>/bigpage.html#xyz</code>. Omitting the [NE] will result in the #
-being converted to its hexcode equivalent, <code>%23</code>, which will
-then result in a 404 Not Found error condition.
-</p>
-
-
-
-<h3><a name="flag_ns" id="flag_ns">NS|nosubreq</a></h3>
-<p>Use of the [NS] flag prevents the rule from being used on
-subrequests. For example, a page which is included using an SSI (Server
-Side Include) is a subrequest, and you may want to avoid rewrites
-happening on those subrequests.</p>
-
-<p>
-Images, javascript files, or css files, loaded as part of an HTML page,
-are not subrequests - the browser requests them as separate HTTP
-requests.
-</p>
-
-
-<h3><a name="flag_p" id="flag_p">P|proxy</a></h3>
-<p>Use of the [P] flag causes the request to be handled by
-<code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, and handled via a proxy request. For
-example, if you wanted all image requests to be handled by a back-end
-image server, you might do something like the following:</p>
-
-<div class="example"><p><code>
-RewriteRule (.*)\.(jpg|gif|png) http://images.example.com$1.$2 [P]
-</code></p></div>
-
-<p>Use of the [P] flag implies [L] - that is, the request is immediatly
-pushed through the proxy, and any following rules will not be
-considered.</p>
-
-
-
-<h3><a name="flag_pt" id="flag_pt">PT|passthrough</a></h3>
-
-<p>
-The target (or substitution string) in a RewriteRule is assumed to be a
-file path, by default. The use of the [PT] flag causes it to be treated
-as a URI instead. That is to say, the
-use of the [PT] flag causes the result of the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be passed back through
-URL mapping, so that location-based mappings, such as <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>, for example, might have a chance to take
-effect.
-</p>
-
-<p>
-If, for example, you have an
-<code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>
-for /icons, and have a <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> pointing there, you should
-use the [PT] flag to ensure that the
-<code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> is evaluated.
-</p>
-
-<div class="example"><p><code>
-Alias /icons /usr/local/apache/icons<br />
-RewriteRule /pics/(.+)\.jpg /icons/$1.gif [PT]
-</code></p></div>
-
-<p>
-Omission of the [PT] flag in this case will cause the Alias to be
-ignored, resulting in a 'File not found' error being returned.
-</p>
-
-
-
-<h3><a name="flag_qsa" id="flag_qsa">QSA|qsappend</a></h3>
-<p>
-When the replacement URI contains a query string, the default behavior
-of <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is to discard
-the existing query string, and replace it with the newly generated one.
-Using the [QSA] flag causes the query strings to be combined.
-</p>
-
-<p>Consider the following rule:</p>
-
-<div class="example"><p><code>
-RewriteRule /pages/(.+) /page.php?page=$1 [QSA]
-</code></p></div>
-
-<p>With the [QSA] flag, a request for <code>/pages/123?one=two</code> will be
-mapped to <code>/page.php?page=123&one=two</code>. Without the [QSA]
-flag, that same request will be mapped to
-<code>/page.php?page=123</code> - that is, the existing query string
-will be discarded.
-</p>
-
-
-<h3><a name="flag_r" id="flag_r">R|redirect</a></h3>
-<p>
-Use of the [R] flag causes a HTTP redirect to be issued to the browser.
-If a fully-qualified URL is specified (that is, including
-<code>http://servername/</code>) then a redirect will be issued to that
-location. Otherwise, the current servername will be used to generate the
-URL sent with the redirect.
-</p>
-
-<p>
-A status code may be specified, in the range 300-399, with a 302 status
-code being used by default if none is specified.
-</p>
-
-<p>
-You will almost always want to use [R] in conjunction with [L] (that is,
-use [R,L]) because on its own, the [R] flag prepends
-<code>http://thishost[:thisport]</code> to the URI, but then passes this
-on to the next rule in the ruleset, which can often result in 'Invalid
-URI in request' warnings.
-</p>
-
-
-
-<h3><a name="flag_s" id="flag_s">S|skip</a></h3>
-<p>The [S] flag is used to skip rules that you don't want to run. This
-can be thought of as a <code>goto</code> statement in your rewrite
-ruleset. In the following example, we only want to run the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> if the requested URI
-doesn't correspond with an actual file.</p>
-
-<div class="example"><p><code>
-# Is the request for a non-existent file?<br />
-RewriteCond %{REQUEST_FILENAME} !-f<br />
-RewriteCond %{REQUEST_FILENAME} !-d<br />
-# If so, skip these two RewriteRules<br />
-RewriteRule .? - [S=2]<br />
-<br />
-RewriteRule (.*\.gif) images.php?$1<br />
-RewriteRule (.*\.html) docs.php?$1
-</code></p></div>
-
-<p>This technique is useful because a <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> only applies to the
-<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> immediately
-following it. Thus, if you want to make a <code>RewriteCond</code> apply
-to several <code>RewriteRule</code>s, one possible technique is to
-negate those conditions and use a [Skip] flag.</p>
-
-
-
-<h3><a name="flag_t" id="flag_t">T|type</a></h3>
-<p>Sets the MIME type with which the resulting response will be
-sent. This has the same effect as the <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> directive.</p>
-
-<p>For example, you might use the following technique to serve Perl
-source code as plain text, if requested in a particular way:</p>
-
-<div class="example"><p><code>
-# Serve .pl files as plain text<br />
-RewriteRule \.pl$ - [T=text/plain]
-</code></p></div>
-
-<p>Or, perhaps, if you have a camera that produces jpeg images without
-file extensions, you could force those images to be served with the
-correct MIME type by virtue of their file names:</p>
-
-<div class="example"><p><code>
-# Files with 'IMG' in the name are jpg images.<br />
-RewriteRule IMG - [T=image/jpg]
-</code></p></div>
-
-<p>Please note that this is a trivial example, and could be better done
-using <code class="directive"><a href="../mod/core.html#filesmatch"><FilesMatch></a></code>
-instead. Always consider the alternate
-solutions to a problem before resorting to rewrite, which will
-invariably be a less efficient solution than the alternatives.</p>
-
-<p>
-If used in per-directory context, use only <code>-</code> (dash)
-as the substitution <em>for the entire round of mod_rewrite processing</em>,
-otherwise the MIME-type set with this flag is lost due to an internal
-re-processing (including subsequent rounds of mod_rewrite processing).
-The <code>L</code> flag can be useful in this context to end the
-<em>current</em> round of mod_rewrite processing.</p>
-
-</div></div>
-<div class="bottomlang">
-<p><span>Available Languages: </span><a href="../en/rewrite/rewrite_flags.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
+++ /dev/null
-<?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>URL Rewriting Guide - 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>URL Rewriting Guide</h1>
-<div class="toplang">
-<p><span>Available Languages: </span><a href="../en/rewrite/rewrite_guide.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 how one can use Apache's <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
- to solve typical URL-based problems with which webmasters are
- commonly confronted. We give detailed descriptions on how to
- solve each problem by configuring URL rewriting rulesets.</p>
-
- <div class="warning">ATTENTION: Depending on your server configuration
- it may be necessary to slightly change the examples for your
- situation, e.g. adding the <code>[PT]</code> flag when
- additionally using <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and
- <code class="module"><a href="../mod/mod_userdir.html">mod_userdir</a></code>, etc. Or rewriting a ruleset
- to fit in <code>.htaccess</code> context instead
- of per-server context. Always try to understand what a
- particular ruleset really does before you use it. This
- avoids many problems.</div>
-
- </div>
-<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#canonicalurl">Canonical URLs</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#canonicalhost">Canonical Hostnames</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#moveddocroot">Moved <code>DocumentRoot</code></a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#trailingslash">Trailing Slash Problem</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#movehomedirs">Move Homedirs to Different Webserver</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#multipledirs">Search pages in more than one directory</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#setenvvars">Set Environment Variables According To URL Parts</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#uservhosts">Virtual User Hosts</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#redirecthome">Redirect Homedirs For Foreigners</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#redirectanchors">Redirecting Anchors</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#time-dependent">Time-Dependent Rewriting</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#backward-compatibility">Backward Compatibility for YYYY to XXXX migration</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#old-to-new">From Old to New (intern)</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#old-to-new-extern">From Old to New (extern)</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#static-to-dynamic">From Static to Dynamic</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#blocking-of-robots">Blocking of Robots</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#blocked-inline-images">Blocked Inline-Images</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#proxy-deny">Proxy Deny</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#external-rewriting">External Rewriting Engine</a></li>
-</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module
-documentation</a></li><li><a href="rewrite_intro.html">mod_rewrite
-introduction</a></li><li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide - advanced
-useful examples</a></li><li><a href="rewrite_tech.html">Technical details</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="canonicalurl" id="canonicalurl">Canonical URLs</a></h2>
-
-
-
-<dl>
- <dt>Description:</dt>
-
- <dd>
- <p>On some webservers there are more than one URL for a
- resource. Usually there are canonical URLs (which should be
- actually used and distributed) and those which are just
- shortcuts, internal ones, etc. Independent of which URL the
- user supplied with the request he should finally see the
- canonical one only.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We do an external HTTP redirect for all non-canonical
- URLs to fix them in the location view of the Browser and
- for all subsequent requests. In the example ruleset below
- we replace <code>/~user</code> by the canonical
- <code>/u/user</code> and fix a missing trailing slash for
- <code>/u/user</code>.</p>
-
-<div class="example"><pre>
-RewriteRule ^/<strong>~</strong>([^/]+)/?(.*) /<strong>u</strong>/$1/$2 [<strong>R</strong>]
-RewriteRule ^/u/(<strong>[^/]+</strong>)$ /$1/$2<strong>/</strong> [<strong>R</strong>]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="canonicalhost" id="canonicalhost">Canonical Hostnames</a></h2>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>The goal of this rule is to force the use of a particular
- hostname, in preference to other hostnames which may be used to
- reach the same site. For example, if you wish to force the use
- of <strong>www.example.com</strong> instead of
- <strong>example.com</strong>, you might use a variant of the
- following recipe.</dd>
-
- <dt>Solution:</dt>
-
- <dd>
-<p>For sites running on a port other than 80:</p>
-<div class="example"><pre>
-RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
-RewriteCond %{HTTP_HOST} !^$
-RewriteCond %{SERVER_PORT} !^80$
-RewriteRule ^/?(.*) http://www.example.com:%{SERVER_PORT}/$1 [L,R,NE]
-</pre></div>
-
-<p>And for a site running on port 80</p>
-<div class="example"><pre>
-RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
-RewriteCond %{HTTP_HOST} !^$
-RewriteRule ^/?(.*) http://www.example.com/$1 [L,R,NE]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="moveddocroot" id="moveddocroot">Moved <code>DocumentRoot</code></a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
-<p>Usually the <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>
-of the webserver directly relates to the URL "<code>/</code>".
-But often this data is not really of top-level priority. For example,
-you may wish for visitors, on first entering a site, to go to a
-particular subdirectory <code>/about/</code>. This may be accomplished
-using the following ruleset:</p>
-</dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We redirect the URL <code>/</code> to
- <code>/about/</code>:
- </p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteRule <strong>^/$</strong> /about/ [<strong>R</strong>]
-</pre></div>
-
- <p>Note that this can also be handled using the <code class="directive"><a href="../mod/mod_alias.html#redirectmatch">RedirectMatch</a></code> directive:</p>
-
-<div class="example"><p><code>
-RedirectMatch ^/$ http://example.com/e/www/
-</code></p></div>
-</dd>
-</dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="trailingslash" id="trailingslash">Trailing Slash Problem</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd><p>The vast majority of "trailing slash" problems can be dealt
- with using the techniques discussed in the <a href="http://httpd.apache.org/docs/misc/FAQ-E.html#set-servername">FAQ
- entry</a>. However, occasionally, there is a need to use mod_rewrite
- to handle a case where a missing trailing slash causes a URL to
- fail. This can happen, for example, after a series of complex
- rewrite rules.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>The solution to this subtle problem is to let the server
- add the trailing slash automatically. To do this
- correctly we have to use an external redirect, so the
- browser correctly requests subsequent images etc. If we
- only did a internal rewrite, this would only work for the
- directory page, but would go wrong when any images are
- included into this page with relative URLs, because the
- browser would request an in-lined object. For instance, a
- request for <code>image.gif</code> in
- <code>/~quux/foo/index.html</code> would become
- <code>/~quux/image.gif</code> without the external
- redirect!</p>
-
- <p>So, to do this trick we write:</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteRule ^foo<strong>$</strong> foo<strong>/</strong> [<strong>R</strong>]
-</pre></div>
-
- <p>Alternately, you can put the following in a
- top-level <code>.htaccess</code> file in the content directory.
- But note that this creates some processing overhead.</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteCond %{REQUEST_FILENAME} <strong>-d</strong>
-RewriteRule ^(.+<strong>[^/]</strong>)$ $1<strong>/</strong> [R]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="movehomedirs" id="movehomedirs">Move Homedirs to Different Webserver</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Many webmasters have asked for a solution to the
- following situation: They wanted to redirect just all
- homedirs on a webserver to another webserver. They usually
- need such things when establishing a newer webserver which
- will replace the old one over time.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>The solution is trivial with <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.
- On the old webserver we just redirect all
- <code>/~user/anypath</code> URLs to
- <code>http://newserver/~user/anypath</code>.</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteRule ^/~(.+) http://<strong>newserver</strong>/~$1 [R,L]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="multipledirs" id="multipledirs">Search pages in more than one directory</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Sometimes it is necessary to let the webserver search
- for pages in more than one directory. Here MultiViews or
- other techniques cannot help.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We program a explicit ruleset which searches for the
- files in the directories.</p>
-
-<div class="example"><pre>
-RewriteEngine on
-
-# first try to find it in dir1/...
-# ...and if found stop and be happy:
-RewriteCond /your/docroot/<strong>dir1</strong>/%{REQUEST_FILENAME} -f
-RewriteRule ^(.+) /your/docroot/<strong>dir1</strong>/$1 [L]
-
-# second try to find it in dir2/...
-# ...and if found stop and be happy:
-RewriteCond /your/docroot/<strong>dir2</strong>/%{REQUEST_FILENAME} -f
-RewriteRule ^(.+) /your/docroot/<strong>dir2</strong>/$1 [L]
-
-# else go on for other Alias or ScriptAlias directives,
-# etc.
-RewriteRule ^(.+) - [PT]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="setenvvars" id="setenvvars">Set Environment Variables According To URL Parts</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Perhaps you want to keep status information between
- requests and use the URL to encode it. But you don't want
- to use a CGI wrapper for all pages just to strip out this
- information.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We use a rewrite rule to strip out the status information
- and remember it via an environment variable which can be
- later dereferenced from within XSSI or CGI. This way a
- URL <code>/foo/S=java/bar/</code> gets translated to
- <code>/foo/bar/</code> and the environment variable named
- <code>STATUS</code> is set to the value "java".</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteRule ^(.*)/<strong>S=([^/]+)</strong>/(.*) $1/$3 [E=<strong>STATUS:$2</strong>]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="uservhosts" id="uservhosts">Virtual User Hosts</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Assume that you want to provide
- <code>www.<strong>username</strong>.host.domain.com</code>
- for the homepage of username via just DNS A records to the
- same machine and without any virtualhosts on this
- machine.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>For HTTP/1.0 requests there is no solution, but for
- HTTP/1.1 requests which contain a Host: HTTP header we
- can use the following ruleset to rewrite
- <code>http://www.username.host.com/anypath</code>
- internally to <code>/home/username/anypath</code>:</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteCond %{<strong>HTTP_HOST</strong>} ^www\.<strong>[^.]+</strong>\.host\.com$
-RewriteRule ^(.+) %{HTTP_HOST}$1 [C]
-RewriteRule ^www\.<strong>([^.]+)</strong>\.host\.com(.*) /home/<strong>$1</strong>$2
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="redirecthome" id="redirecthome">Redirect Homedirs For Foreigners</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>We want to redirect homedir URLs to another webserver
- <code>www.somewhere.com</code> when the requesting user
- does not stay in the local domain
- <code>ourdomain.com</code>. This is sometimes used in
- virtual host contexts.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>Just a rewrite condition:</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteCond %{REMOTE_HOST} <strong>!^.+\.ourdomain\.com$</strong>
-RewriteRule ^(/~.+) http://www.somewhere.com/$1 [R,L]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="redirectanchors" id="redirectanchors">Redirecting Anchors</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>By default, redirecting to an HTML anchor doesn't work,
- because mod_rewrite escapes the <code>#</code> character,
- turning it into <code>%23</code>. This, in turn, breaks the
- redirection.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>Use the <code>[NE]</code> flag on the
- <code>RewriteRule</code>. NE stands for No Escape.
- </p>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="time-dependent" id="time-dependent">Time-Dependent Rewriting</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>When tricks like time-dependent content should happen a
- lot of webmasters still use CGI scripts which do for
- instance redirects to specialized pages. How can it be done
- via <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>There are a lot of variables named <code>TIME_xxx</code>
- for rewrite conditions. In conjunction with the special
- lexicographic comparison patterns <code><STRING</code>,
- <code>>STRING</code> and <code>=STRING</code> we can
- do time-dependent redirects:</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteCond %{TIME_HOUR}%{TIME_MIN} >0700
-RewriteCond %{TIME_HOUR}%{TIME_MIN} <1900
-RewriteRule ^foo\.html$ foo.day.html
-RewriteRule ^foo\.html$ foo.night.html
-</pre></div>
-
- <p>This provides the content of <code>foo.day.html</code>
- under the URL <code>foo.html</code> from
- <code>07:00-19:00</code> and at the remaining time the
- contents of <code>foo.night.html</code>. Just a nice
- feature for a homepage...</p>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="backward-compatibility" id="backward-compatibility">Backward Compatibility for YYYY to XXXX migration</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we make URLs backward compatible (still
- existing virtually) after migrating <code>document.YYYY</code>
- to <code>document.XXXX</code>, e.g. after translating a
- bunch of <code>.html</code> files to <code>.phtml</code>?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We just rewrite the name to its basename and test for
- existence of the new extension. If it exists, we take
- that name, else we rewrite the URL to its original state.</p>
-
-
-<div class="example"><pre>
-# backward compatibility ruleset for
-# rewriting document.html to document.phtml
-# when and only when document.phtml exists
-# but no longer document.html
-RewriteEngine on
-RewriteBase /~quux/
-# parse out basename, but remember the fact
-RewriteRule ^(.*)\.html$ $1 [C,E=WasHTML:yes]
-# rewrite to document.phtml if exists
-RewriteCond %{REQUEST_FILENAME}.phtml -f
-RewriteRule ^(.*)$ $1.phtml [S=1]
-# else reverse the previous basename cutout
-RewriteCond %{ENV:WasHTML} ^yes$
-RewriteRule ^(.*)$ $1.html
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="old-to-new" id="old-to-new">From Old to New (intern)</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Assume we have recently renamed the page
- <code>foo.html</code> to <code>bar.html</code> and now want
- to provide the old URL for backward compatibility. Actually
- we want that users of the old URL even not recognize that
- the pages was renamed.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We rewrite the old URL to the new one internally via the
- following rule:</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteRule ^<strong>foo</strong>\.html$ <strong>bar</strong>.html
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="old-to-new-extern" id="old-to-new-extern">From Old to New (extern)</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Assume again that we have recently renamed the page
- <code>foo.html</code> to <code>bar.html</code> and now want
- to provide the old URL for backward compatibility. But this
- time we want that the users of the old URL get hinted to
- the new one, i.e. their browsers Location field should
- change, too.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We force a HTTP redirect to the new URL which leads to a
- change of the browsers and thus the users view:</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteRule ^<strong>foo</strong>\.html$ <strong>bar</strong>.html [<strong>R</strong>]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="static-to-dynamic" id="static-to-dynamic">From Static to Dynamic</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we transform a static page
- <code>foo.html</code> into a dynamic variant
- <code>foo.cgi</code> in a seamless way, i.e. without notice
- by the browser/user.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We just rewrite the URL to the CGI-script and force the
- handler to be <strong>cgi-script</strong> so that it is
- executed as a CGI program.
- This way a request to <code>/~quux/foo.html</code>
- internally leads to the invocation of
- <code>/~quux/foo.cgi</code>.</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteRule ^foo\.<strong>html</strong>$ foo.<strong>cgi</strong> [H=<strong>cgi-script</strong>]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="blocking-of-robots" id="blocking-of-robots">Blocking of Robots</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we block a really annoying robot from
- retrieving pages of a specific webarea? A
- <code>/robots.txt</code> file containing entries of the
- "Robot Exclusion Protocol" is typically not enough to get
- rid of such a robot.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We use a ruleset which forbids the URLs of the webarea
- <code>/~quux/foo/arc/</code> (perhaps a very deep
- directory indexed area where the robot traversal would
- create big server load). We have to make sure that we
- forbid access only to the particular robot, i.e. just
- forbidding the host where the robot runs is not enough.
- This would block users from this host, too. We accomplish
- this by also matching the User-Agent HTTP header
- information.</p>
-
-<div class="example"><pre>
-RewriteCond %{HTTP_USER_AGENT} ^<strong>NameOfBadRobot</strong>.*
-RewriteCond %{REMOTE_ADDR} ^<strong>123\.45\.67\.[8-9]</strong>$
-RewriteRule ^<strong>/~quux/foo/arc/</strong>.+ - [<strong>F</strong>]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="blocked-inline-images" id="blocked-inline-images">Blocked Inline-Images</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Assume we have under <code>http://www.quux-corp.de/~quux/</code>
- some pages with inlined GIF graphics. These graphics are
- nice, so others directly incorporate them via hyperlinks to
- their pages. We don't like this practice because it adds
- useless traffic to our server.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>While we cannot 100% protect the images from inclusion,
- we can at least restrict the cases where the browser
- sends a HTTP Referer header.</p>
-
-<div class="example"><pre>
-RewriteCond %{HTTP_REFERER} <strong>!^$</strong>
-RewriteCond %{HTTP_REFERER} !^http://www.quux-corp.de/~quux/.*$ [NC]
-RewriteRule <strong>.*\.gif$</strong> - [F]
-</pre></div>
-
-<div class="example"><pre>
-RewriteCond %{HTTP_REFERER} !^$
-RewriteCond %{HTTP_REFERER} !.*/foo-with-gif\.html$
-RewriteRule <strong>^inlined-in-foo\.gif$</strong> - [F]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="proxy-deny" id="proxy-deny">Proxy Deny</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we forbid a certain host or even a user of a
- special host from using the Apache proxy?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We first have to make sure <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
- is below(!) <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> in the Configuration
- file when compiling the Apache webserver. This way it gets
- called <em>before</em> <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>. Then we
- configure the following for a host-dependent deny...</p>
-
-<div class="example"><pre>
-RewriteCond %{REMOTE_HOST} <strong>^badhost\.mydomain\.com$</strong>
-RewriteRule !^http://[^/.]\.mydomain.com.* - [F]
-</pre></div>
-
- <p>...and this one for a user@host-dependent deny:</p>
-
-<div class="example"><pre>
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>^badguy@badhost\.mydomain\.com$</strong>
-RewriteRule !^http://[^/.]\.mydomain.com.* - [F]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="external-rewriting" id="external-rewriting">External Rewriting Engine</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>A FAQ: How can we solve the FOO/BAR/QUUX/etc.
- problem? There seems no solution by the use of
- <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>...</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>Use an external <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code>, i.e. a program which acts
- like a <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code>. It is run once on startup of Apache
- receives the requested URLs on <code>STDIN</code> and has
- to put the resulting (usually rewritten) URL on
- <code>STDOUT</code> (same order!).</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteMap quux-map <strong>prg:</strong>/path/to/map.quux.pl
-RewriteRule ^/~quux/(.*)$ /~quux/<strong>${quux-map:$1}</strong>
-</pre></div>
-
-<div class="example"><pre>
-#!/path/to/perl
-
-# disable buffered I/O which would lead
-# to deadloops for the Apache server
-$| = 1;
-
-# read URLs one per line from stdin and
-# generate substitution URL on stdout
-while (<>) {
- s|^foo/|bar/|;
- print $_;
-}
-</pre></div>
-
- <p>This is a demonstration-only example and just rewrites
- all URLs <code>/~quux/foo/...</code> to
- <code>/~quux/bar/...</code>. Actually you can program
- whatever you like. But notice that while such maps can be
- <strong>used</strong> also by an average user, only the
- system administrator can <strong>define</strong> it.</p>
- </dd>
- </dl>
-
- </div></div>
-<div class="bottomlang">
-<p><span>Available Languages: </span><a href="../en/rewrite/rewrite_guide.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
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
-<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<!-- $LastChangedRevision$ -->
-
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
-<manualpage metafile="rewrite_guide.xml.meta">
- <parentdocument href="./">Rewrite</parentdocument>
-
- <title>URL Rewriting Guide</title>
-
- <summary>
-
- <p>This document supplements the <module>mod_rewrite</module>
- <a href="../mod/mod_rewrite.html">reference documentation</a>.
- It describes how one can use Apache's <module>mod_rewrite</module>
- to solve typical URL-based problems with which webmasters are
- commonly confronted. We give detailed descriptions on how to
- solve each problem by configuring URL rewriting rulesets.</p>
-
- <note type="warning">ATTENTION: Depending on your server configuration
- it may be necessary to slightly change the examples for your
- situation, e.g. adding the <code>[PT]</code> flag when
- additionally using <module>mod_alias</module> and
- <module>mod_userdir</module>, etc. Or rewriting a ruleset
- to fit in <code>.htaccess</code> context instead
- of per-server context. Always try to understand what a
- particular ruleset really does before you use it. This
- avoids many problems.</note>
-
- </summary>
-<seealso><a href="../mod/mod_rewrite.html">Module
-documentation</a></seealso>
-<seealso><a href="rewrite_intro.html">mod_rewrite
-introduction</a></seealso>
-<seealso><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide - advanced
-useful examples</a></seealso>
-<seealso><a href="rewrite_tech.html">Technical details</a></seealso>
-
-
-<section id="canonicalurl">
-
-<title>Canonical URLs</title>
-
-<dl>
- <dt>Description:</dt>
-
- <dd>
- <p>On some webservers there are more than one URL for a
- resource. Usually there are canonical URLs (which should be
- actually used and distributed) and those which are just
- shortcuts, internal ones, etc. Independent of which URL the
- user supplied with the request he should finally see the
- canonical one only.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We do an external HTTP redirect for all non-canonical
- URLs to fix them in the location view of the Browser and
- for all subsequent requests. In the example ruleset below
- we replace <code>/~user</code> by the canonical
- <code>/u/user</code> and fix a missing trailing slash for
- <code>/u/user</code>.</p>
-
-<example><pre>
-RewriteRule ^/<strong>~</strong>([^/]+)/?(.*) /<strong>u</strong>/$1/$2 [<strong>R</strong>]
-RewriteRule ^/u/(<strong>[^/]+</strong>)$ /$1/$2<strong>/</strong> [<strong>R</strong>]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
-<section id="canonicalhost"><title>Canonical Hostnames</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>The goal of this rule is to force the use of a particular
- hostname, in preference to other hostnames which may be used to
- reach the same site. For example, if you wish to force the use
- of <strong>www.example.com</strong> instead of
- <strong>example.com</strong>, you might use a variant of the
- following recipe.</dd>
-
- <dt>Solution:</dt>
-
- <dd>
-<p>For sites running on a port other than 80:</p>
-<example><pre>
-RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
-RewriteCond %{HTTP_HOST} !^$
-RewriteCond %{SERVER_PORT} !^80$
-RewriteRule ^/?(.*) http://www.example.com:%{SERVER_PORT}/$1 [L,R,NE]
-</pre></example>
-
-<p>And for a site running on port 80</p>
-<example><pre>
-RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
-RewriteCond %{HTTP_HOST} !^$
-RewriteRule ^/?(.*) http://www.example.com/$1 [L,R,NE]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="moveddocroot">
-
- <title>Moved <code>DocumentRoot</code></title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
-<p>Usually the <directive module="core">DocumentRoot</directive>
-of the webserver directly relates to the URL "<code>/</code>".
-But often this data is not really of top-level priority. For example,
-you may wish for visitors, on first entering a site, to go to a
-particular subdirectory <code>/about/</code>. This may be accomplished
-using the following ruleset:</p>
-</dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We redirect the URL <code>/</code> to
- <code>/about/</code>:
- </p>
-
-<example><pre>
-RewriteEngine on
-RewriteRule <strong>^/$</strong> /about/ [<strong>R</strong>]
-</pre></example>
-
- <p>Note that this can also be handled using the <directive
- module="mod_alias">RedirectMatch</directive> directive:</p>
-
-<example>
-RedirectMatch ^/$ http://example.com/e/www/
-</example>
-</dd>
-</dl>
-
- </section>
-
- <section id="trailingslash">
-
- <title>Trailing Slash Problem</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd><p>The vast majority of "trailing slash" problems can be dealt
- with using the techniques discussed in the <a
- href="http://httpd.apache.org/docs/misc/FAQ-E.html#set-servername">FAQ
- entry</a>. However, occasionally, there is a need to use mod_rewrite
- to handle a case where a missing trailing slash causes a URL to
- fail. This can happen, for example, after a series of complex
- rewrite rules.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>The solution to this subtle problem is to let the server
- add the trailing slash automatically. To do this
- correctly we have to use an external redirect, so the
- browser correctly requests subsequent images etc. If we
- only did a internal rewrite, this would only work for the
- directory page, but would go wrong when any images are
- included into this page with relative URLs, because the
- browser would request an in-lined object. For instance, a
- request for <code>image.gif</code> in
- <code>/~quux/foo/index.html</code> would become
- <code>/~quux/image.gif</code> without the external
- redirect!</p>
-
- <p>So, to do this trick we write:</p>
-
-<example><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteRule ^foo<strong>$</strong> foo<strong>/</strong> [<strong>R</strong>]
-</pre></example>
-
- <p>Alternately, you can put the following in a
- top-level <code>.htaccess</code> file in the content directory.
- But note that this creates some processing overhead.</p>
-
-<example><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteCond %{REQUEST_FILENAME} <strong>-d</strong>
-RewriteRule ^(.+<strong>[^/]</strong>)$ $1<strong>/</strong> [R]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="movehomedirs">
-
- <title>Move Homedirs to Different Webserver</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Many webmasters have asked for a solution to the
- following situation: They wanted to redirect just all
- homedirs on a webserver to another webserver. They usually
- need such things when establishing a newer webserver which
- will replace the old one over time.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>The solution is trivial with <module>mod_rewrite</module>.
- On the old webserver we just redirect all
- <code>/~user/anypath</code> URLs to
- <code>http://newserver/~user/anypath</code>.</p>
-
-<example><pre>
-RewriteEngine on
-RewriteRule ^/~(.+) http://<strong>newserver</strong>/~$1 [R,L]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="multipledirs">
-
- <title>Search pages in more than one directory</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Sometimes it is necessary to let the webserver search
- for pages in more than one directory. Here MultiViews or
- other techniques cannot help.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We program a explicit ruleset which searches for the
- files in the directories.</p>
-
-<example><pre>
-RewriteEngine on
-
-# first try to find it in dir1/...
-# ...and if found stop and be happy:
-RewriteCond /your/docroot/<strong>dir1</strong>/%{REQUEST_FILENAME} -f
-RewriteRule ^(.+) /your/docroot/<strong>dir1</strong>/$1 [L]
-
-# second try to find it in dir2/...
-# ...and if found stop and be happy:
-RewriteCond /your/docroot/<strong>dir2</strong>/%{REQUEST_FILENAME} -f
-RewriteRule ^(.+) /your/docroot/<strong>dir2</strong>/$1 [L]
-
-# else go on for other Alias or ScriptAlias directives,
-# etc.
-RewriteRule ^(.+) - [PT]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="setenvvars">
-
- <title>Set Environment Variables According To URL Parts</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Perhaps you want to keep status information between
- requests and use the URL to encode it. But you don't want
- to use a CGI wrapper for all pages just to strip out this
- information.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We use a rewrite rule to strip out the status information
- and remember it via an environment variable which can be
- later dereferenced from within XSSI or CGI. This way a
- URL <code>/foo/S=java/bar/</code> gets translated to
- <code>/foo/bar/</code> and the environment variable named
- <code>STATUS</code> is set to the value "java".</p>
-
-<example><pre>
-RewriteEngine on
-RewriteRule ^(.*)/<strong>S=([^/]+)</strong>/(.*) $1/$3 [E=<strong>STATUS:$2</strong>]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="uservhosts">
-
- <title>Virtual User Hosts</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Assume that you want to provide
- <code>www.<strong>username</strong>.host.domain.com</code>
- for the homepage of username via just DNS A records to the
- same machine and without any virtualhosts on this
- machine.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>For HTTP/1.0 requests there is no solution, but for
- HTTP/1.1 requests which contain a Host: HTTP header we
- can use the following ruleset to rewrite
- <code>http://www.username.host.com/anypath</code>
- internally to <code>/home/username/anypath</code>:</p>
-
-<example><pre>
-RewriteEngine on
-RewriteCond %{<strong>HTTP_HOST</strong>} ^www\.<strong>[^.]+</strong>\.host\.com$
-RewriteRule ^(.+) %{HTTP_HOST}$1 [C]
-RewriteRule ^www\.<strong>([^.]+)</strong>\.host\.com(.*) /home/<strong>$1</strong>$2
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="redirecthome">
-
- <title>Redirect Homedirs For Foreigners</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>We want to redirect homedir URLs to another webserver
- <code>www.somewhere.com</code> when the requesting user
- does not stay in the local domain
- <code>ourdomain.com</code>. This is sometimes used in
- virtual host contexts.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>Just a rewrite condition:</p>
-
-<example><pre>
-RewriteEngine on
-RewriteCond %{REMOTE_HOST} <strong>!^.+\.ourdomain\.com$</strong>
-RewriteRule ^(/~.+) http://www.somewhere.com/$1 [R,L]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="redirectanchors">
-
- <title>Redirecting Anchors</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>By default, redirecting to an HTML anchor doesn't work,
- because mod_rewrite escapes the <code>#</code> character,
- turning it into <code>%23</code>. This, in turn, breaks the
- redirection.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>Use the <code>[NE]</code> flag on the
- <code>RewriteRule</code>. NE stands for No Escape.
- </p>
- </dd>
- </dl>
-
- </section>
-
- <section id="time-dependent">
-
- <title>Time-Dependent Rewriting</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>When tricks like time-dependent content should happen a
- lot of webmasters still use CGI scripts which do for
- instance redirects to specialized pages. How can it be done
- via <module>mod_rewrite</module>?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>There are a lot of variables named <code>TIME_xxx</code>
- for rewrite conditions. In conjunction with the special
- lexicographic comparison patterns <code><STRING</code>,
- <code>>STRING</code> and <code>=STRING</code> we can
- do time-dependent redirects:</p>
-
-<example><pre>
-RewriteEngine on
-RewriteCond %{TIME_HOUR}%{TIME_MIN} >0700
-RewriteCond %{TIME_HOUR}%{TIME_MIN} <1900
-RewriteRule ^foo\.html$ foo.day.html
-RewriteRule ^foo\.html$ foo.night.html
-</pre></example>
-
- <p>This provides the content of <code>foo.day.html</code>
- under the URL <code>foo.html</code> from
- <code>07:00-19:00</code> and at the remaining time the
- contents of <code>foo.night.html</code>. Just a nice
- feature for a homepage...</p>
- </dd>
- </dl>
-
- </section>
-
- <section id="backward-compatibility">
-
- <title>Backward Compatibility for YYYY to XXXX migration</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we make URLs backward compatible (still
- existing virtually) after migrating <code>document.YYYY</code>
- to <code>document.XXXX</code>, e.g. after translating a
- bunch of <code>.html</code> files to <code>.phtml</code>?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We just rewrite the name to its basename and test for
- existence of the new extension. If it exists, we take
- that name, else we rewrite the URL to its original state.</p>
-
-
-<example><pre>
-# backward compatibility ruleset for
-# rewriting document.html to document.phtml
-# when and only when document.phtml exists
-# but no longer document.html
-RewriteEngine on
-RewriteBase /~quux/
-# parse out basename, but remember the fact
-RewriteRule ^(.*)\.html$ $1 [C,E=WasHTML:yes]
-# rewrite to document.phtml if exists
-RewriteCond %{REQUEST_FILENAME}.phtml -f
-RewriteRule ^(.*)$ $1.phtml [S=1]
-# else reverse the previous basename cutout
-RewriteCond %{ENV:WasHTML} ^yes$
-RewriteRule ^(.*)$ $1.html
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="old-to-new">
-
- <title>From Old to New (intern)</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Assume we have recently renamed the page
- <code>foo.html</code> to <code>bar.html</code> and now want
- to provide the old URL for backward compatibility. Actually
- we want that users of the old URL even not recognize that
- the pages was renamed.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We rewrite the old URL to the new one internally via the
- following rule:</p>
-
-<example><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteRule ^<strong>foo</strong>\.html$ <strong>bar</strong>.html
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="old-to-new-extern">
-
- <title>From Old to New (extern)</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Assume again that we have recently renamed the page
- <code>foo.html</code> to <code>bar.html</code> and now want
- to provide the old URL for backward compatibility. But this
- time we want that the users of the old URL get hinted to
- the new one, i.e. their browsers Location field should
- change, too.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We force a HTTP redirect to the new URL which leads to a
- change of the browsers and thus the users view:</p>
-
-<example><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteRule ^<strong>foo</strong>\.html$ <strong>bar</strong>.html [<strong>R</strong>]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="static-to-dynamic">
-
- <title>From Static to Dynamic</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we transform a static page
- <code>foo.html</code> into a dynamic variant
- <code>foo.cgi</code> in a seamless way, i.e. without notice
- by the browser/user.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We just rewrite the URL to the CGI-script and force the
- handler to be <strong>cgi-script</strong> so that it is
- executed as a CGI program.
- This way a request to <code>/~quux/foo.html</code>
- internally leads to the invocation of
- <code>/~quux/foo.cgi</code>.</p>
-
-<example><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteRule ^foo\.<strong>html</strong>$ foo.<strong>cgi</strong> [H=<strong>cgi-script</strong>]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="blocking-of-robots">
-
- <title>Blocking of Robots</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we block a really annoying robot from
- retrieving pages of a specific webarea? A
- <code>/robots.txt</code> file containing entries of the
- "Robot Exclusion Protocol" is typically not enough to get
- rid of such a robot.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We use a ruleset which forbids the URLs of the webarea
- <code>/~quux/foo/arc/</code> (perhaps a very deep
- directory indexed area where the robot traversal would
- create big server load). We have to make sure that we
- forbid access only to the particular robot, i.e. just
- forbidding the host where the robot runs is not enough.
- This would block users from this host, too. We accomplish
- this by also matching the User-Agent HTTP header
- information.</p>
-
-<example><pre>
-RewriteCond %{HTTP_USER_AGENT} ^<strong>NameOfBadRobot</strong>.*
-RewriteCond %{REMOTE_ADDR} ^<strong>123\.45\.67\.[8-9]</strong>$
-RewriteRule ^<strong>/~quux/foo/arc/</strong>.+ - [<strong>F</strong>]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="blocked-inline-images">
-
- <title>Blocked Inline-Images</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Assume we have under <code>http://www.quux-corp.de/~quux/</code>
- some pages with inlined GIF graphics. These graphics are
- nice, so others directly incorporate them via hyperlinks to
- their pages. We don't like this practice because it adds
- useless traffic to our server.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>While we cannot 100% protect the images from inclusion,
- we can at least restrict the cases where the browser
- sends a HTTP Referer header.</p>
-
-<example><pre>
-RewriteCond %{HTTP_REFERER} <strong>!^$</strong>
-RewriteCond %{HTTP_REFERER} !^http://www.quux-corp.de/~quux/.*$ [NC]
-RewriteRule <strong>.*\.gif$</strong> - [F]
-</pre></example>
-
-<example><pre>
-RewriteCond %{HTTP_REFERER} !^$
-RewriteCond %{HTTP_REFERER} !.*/foo-with-gif\.html$
-RewriteRule <strong>^inlined-in-foo\.gif$</strong> - [F]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="proxy-deny">
-
- <title>Proxy Deny</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we forbid a certain host or even a user of a
- special host from using the Apache proxy?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We first have to make sure <module>mod_rewrite</module>
- is below(!) <module>mod_proxy</module> in the Configuration
- file when compiling the Apache webserver. This way it gets
- called <em>before</em> <module>mod_proxy</module>. Then we
- configure the following for a host-dependent deny...</p>
-
-<example><pre>
-RewriteCond %{REMOTE_HOST} <strong>^badhost\.mydomain\.com$</strong>
-RewriteRule !^http://[^/.]\.mydomain.com.* - [F]
-</pre></example>
-
- <p>...and this one for a user@host-dependent deny:</p>
-
-<example><pre>
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>^badguy@badhost\.mydomain\.com$</strong>
-RewriteRule !^http://[^/.]\.mydomain.com.* - [F]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="external-rewriting">
-
- <title>External Rewriting Engine</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>A FAQ: How can we solve the FOO/BAR/QUUX/etc.
- problem? There seems no solution by the use of
- <module>mod_rewrite</module>...</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>Use an external <directive module="mod_rewrite"
- >RewriteMap</directive>, i.e. a program which acts
- like a <directive module="mod_rewrite"
- >RewriteMap</directive>. It is run once on startup of Apache
- receives the requested URLs on <code>STDIN</code> and has
- to put the resulting (usually rewritten) URL on
- <code>STDOUT</code> (same order!).</p>
-
-<example><pre>
-RewriteEngine on
-RewriteMap quux-map <strong>prg:</strong>/path/to/map.quux.pl
-RewriteRule ^/~quux/(.*)$ /~quux/<strong>${quux-map:$1}</strong>
-</pre></example>
-
-<example><pre>
-#!/path/to/perl
-
-# disable buffered I/O which would lead
-# to deadloops for the Apache server
-$| = 1;
-
-# read URLs one per line from stdin and
-# generate substitution URL on stdout
-while (<>) {
- s|^foo/|bar/|;
- print $_;
-}
-</pre></example>
-
- <p>This is a demonstration-only example and just rewrites
- all URLs <code>/~quux/foo/...</code> to
- <code>/~quux/bar/...</code>. Actually you can program
- whatever you like. But notice that while such maps can be
- <strong>used</strong> also by an average user, only the
- system administrator can <strong>define</strong> it.</p>
- </dd>
- </dl>
-
- </section>
-
-</manualpage>
-
+++ /dev/null
-<?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>URL Rewriting Guide - Advanced topics - 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>URL Rewriting Guide - Advanced topics</h1>
-<div class="toplang">
-<p><span>Available Languages: </span><a href="../en/rewrite/rewrite_guide_advanced.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 how one can use Apache's <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
- to solve typical URL-based problems with which webmasters are
- commonly confronted. We give detailed descriptions on how to
- solve each problem by configuring URL rewriting rulesets.</p>
-
- <div class="warning">ATTENTION: Depending on your server configuration
- it may be necessary to adjust the examples for your
- situation, e.g., adding the <code>[PT]</code> flag if
- using <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and
- <code class="module"><a href="../mod/mod_userdir.html">mod_userdir</a></code>, etc. Or rewriting a ruleset
- to work in <code>.htaccess</code> context instead
- of per-server context. Always try to understand what a
- particular ruleset really does before you use it; this
- avoids many problems.</div>
-
- </div>
-<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#cluster">Web Cluster with Consistent URL Space</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#structuredhomedirs">Structured Homedirs</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#filereorg">Filesystem Reorganization</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#redirect404">Redirect Failing URLs to Another Web Server</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#archive-access-multiplexer">Archive Access Multiplexer</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#browser-dependent-content">Browser Dependent Content</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#dynamic-mirror">Dynamic Mirror</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#reverse-dynamic-mirror">Reverse Dynamic Mirror</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#retrieve-missing-data">Retrieve Missing Data from Intranet</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#load-balancing">Load Balancing</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#new-mime-type">New MIME-type, New Service</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#on-the-fly-content">On-the-fly Content-Regeneration</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#autorefresh">Document With Autorefresh</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#mass-virtual-hosting">Mass Virtual Hosting</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#host-deny">Host Deny</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#proxy-deny">Proxy Deny</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#special-authentication">Special Authentication Variant</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#referer-deflector">Referer-based Deflector</a></li>
-</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module
-documentation</a></li><li><a href="rewrite_intro.html">mod_rewrite
-introduction</a></li><li><a href="rewrite_guide.html">Rewrite Guide - useful
-examples</a></li><li><a href="rewrite_tech.html">Technical details</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="cluster" id="cluster">Web Cluster with Consistent URL Space</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>We want to create a homogeneous and consistent URL
- layout across all WWW servers on an Intranet web cluster, i.e.,
- all URLs (by definition server-local and thus
- server-dependent!) become server <em>independent</em>!
- What we want is to give the WWW namespace a single consistent
- layout: no URL should refer to
- any particular target server. The cluster itself
- should connect users automatically to a physical target
- host as needed, invisibly.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>First, the knowledge of the target servers comes from
- (distributed) external maps which contain information on
- where our users, groups, and entities reside. They have the
- form:</p>
-
-<div class="example"><pre>
-user1 server_of_user1
-user2 server_of_user2
-: :
-</pre></div>
-
- <p>We put them into files <code>map.xxx-to-host</code>.
- Second we need to instruct all servers to redirect URLs
- of the forms:</p>
-
-<div class="example"><pre>
-/u/user/anypath
-/g/group/anypath
-/e/entity/anypath
-</pre></div>
-
- <p>to</p>
-
-<div class="example"><pre>
-http://physical-host/u/user/anypath
-http://physical-host/g/group/anypath
-http://physical-host/e/entity/anypath
-</pre></div>
-
- <p>when any URL path need not be valid on every server. The
- following ruleset does this for us with the help of the map
- files (assuming that server0 is a default server which
- will be used if a user has no entry in the map):</p>
-
-<div class="example"><pre>
-RewriteEngine on
-
-RewriteMap user-to-host txt:/path/to/map.user-to-host
-RewriteMap group-to-host txt:/path/to/map.group-to-host
-RewriteMap entity-to-host txt:/path/to/map.entity-to-host
-
-RewriteRule ^/u/<strong>([^/]+)</strong>/?(.*) http://<strong>${user-to-host:$1|server0}</strong>/u/$1/$2
-RewriteRule ^/g/<strong>([^/]+)</strong>/?(.*) http://<strong>${group-to-host:$1|server0}</strong>/g/$1/$2
-RewriteRule ^/e/<strong>([^/]+)</strong>/?(.*) http://<strong>${entity-to-host:$1|server0}</strong>/e/$1/$2
-
-RewriteRule ^/([uge])/([^/]+)/?$ /$1/$2/.www/
-RewriteRule ^/([uge])/([^/]+)/([^.]+.+) /$1/$2/.www/$3\
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="structuredhomedirs" id="structuredhomedirs">Structured Homedirs</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Some sites with thousands of users use a
- structured homedir layout, <em>i.e.</em> each homedir is in a
- subdirectory which begins (for instance) with the first
- character of the username. So, <code>/~foo/anypath</code>
- is <code>/home/<strong>f</strong>/foo/.www/anypath</code>
- while <code>/~bar/anypath</code> is
- <code>/home/<strong>b</strong>/bar/.www/anypath</code>.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We use the following ruleset to expand the tilde URLs
- into the above layout.</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteRule ^/~(<strong>([a-z])</strong>[a-z0-9]+)(.*) /home/<strong>$2</strong>/$1/.www$3
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="filereorg" id="filereorg">Filesystem Reorganization</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>This really is a hardcore example: a killer application
- which heavily uses per-directory
- <code>RewriteRules</code> to get a smooth look and feel
- on the Web while its data structure is never touched or
- adjusted. Background: <strong><em>net.sw</em></strong> is
- my archive of freely available Unix software packages,
- which I started to collect in 1992. It is both my hobby
- and job to do this, because while I'm studying computer
- science I have also worked for many years as a system and
- network administrator in my spare time. Every week I need
- some sort of software so I created a deep hierarchy of
- directories where I stored the packages:</p>
-
-<div class="example"><pre>
-drwxrwxr-x 2 netsw users 512 Aug 3 18:39 Audio/
-drwxrwxr-x 2 netsw users 512 Jul 9 14:37 Benchmark/
-drwxrwxr-x 12 netsw users 512 Jul 9 00:34 Crypto/
-drwxrwxr-x 5 netsw users 512 Jul 9 00:41 Database/
-drwxrwxr-x 4 netsw users 512 Jul 30 19:25 Dicts/
-drwxrwxr-x 10 netsw users 512 Jul 9 01:54 Graphic/
-drwxrwxr-x 5 netsw users 512 Jul 9 01:58 Hackers/
-drwxrwxr-x 8 netsw users 512 Jul 9 03:19 InfoSys/
-drwxrwxr-x 3 netsw users 512 Jul 9 03:21 Math/
-drwxrwxr-x 3 netsw users 512 Jul 9 03:24 Misc/
-drwxrwxr-x 9 netsw users 512 Aug 1 16:33 Network/
-drwxrwxr-x 2 netsw users 512 Jul 9 05:53 Office/
-drwxrwxr-x 7 netsw users 512 Jul 9 09:24 SoftEng/
-drwxrwxr-x 7 netsw users 512 Jul 9 12:17 System/
-drwxrwxr-x 12 netsw users 512 Aug 3 20:15 Typesetting/
-drwxrwxr-x 10 netsw users 512 Jul 9 14:08 X11/
-</pre></div>
-
- <p>In July 1996 I decided to make this archive public to
- the world via a nice Web interface. "Nice" means that I
- wanted to offer an interface where you can browse
- directly through the archive hierarchy. And "nice" means
- that I didn't want to change anything inside this
- hierarchy - not even by putting some CGI scripts at the
- top of it. Why? Because the above structure should later be
- accessible via FTP as well, and I didn't want any
- Web or CGI stuff mixed in there.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>The solution has two parts: The first is a set of CGI
- scripts which create all the pages at all directory
- levels on-the-fly. I put them under
- <code>/e/netsw/.www/</code> as follows:</p>
-
-<div class="example"><pre>
--rw-r--r-- 1 netsw users 1318 Aug 1 18:10 .wwwacl
-drwxr-xr-x 18 netsw users 512 Aug 5 15:51 DATA/
--rw-rw-rw- 1 netsw users 372982 Aug 5 16:35 LOGFILE
--rw-r--r-- 1 netsw users 659 Aug 4 09:27 TODO
--rw-r--r-- 1 netsw users 5697 Aug 1 18:01 netsw-about.html
--rwxr-xr-x 1 netsw users 579 Aug 2 10:33 netsw-access.pl
--rwxr-xr-x 1 netsw users 1532 Aug 1 17:35 netsw-changes.cgi
--rwxr-xr-x 1 netsw users 2866 Aug 5 14:49 netsw-home.cgi
-drwxr-xr-x 2 netsw users 512 Jul 8 23:47 netsw-img/
--rwxr-xr-x 1 netsw users 24050 Aug 5 15:49 netsw-lsdir.cgi
--rwxr-xr-x 1 netsw users 1589 Aug 3 18:43 netsw-search.cgi
--rwxr-xr-x 1 netsw users 1885 Aug 1 17:41 netsw-tree.cgi
--rw-r--r-- 1 netsw users 234 Jul 30 16:35 netsw-unlimit.lst
-</pre></div>
-
- <p>The <code>DATA/</code> subdirectory holds the above
- directory structure, <em>i.e.</em> the real
- <strong><em>net.sw</em></strong> stuff, and gets
- automatically updated via <code>rdist</code> from time to
- time. The second part of the problem remains: how to link
- these two structures together into one smooth-looking URL
- tree? We want to hide the <code>DATA/</code> directory
- from the user while running the appropriate CGI scripts
- for the various URLs. Here is the solution: first I put
- the following into the per-directory configuration file
- in the <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>
- of the server to rewrite the public URL path
- <code>/net.sw/</code> to the internal path
- <code>/e/netsw</code>:</p>
-
-<div class="example"><pre>
-RewriteRule ^net.sw$ net.sw/ [R]
-RewriteRule ^net.sw/(.*)$ e/netsw/$1
-</pre></div>
-
- <p>The first rule is for requests which miss the trailing
- slash! The second rule does the real thing. And then
- comes the killer configuration which stays in the
- per-directory config file
- <code>/e/netsw/.www/.wwwacl</code>:</p>
-
-<div class="example"><pre>
-Options ExecCGI FollowSymLinks Includes MultiViews
-
-RewriteEngine on
-
-# we are reached via /net.sw/ prefix
-RewriteBase /net.sw/
-
-# first we rewrite the root dir to
-# the handling cgi script
-RewriteRule ^$ netsw-home.cgi [L]
-RewriteRule ^index\.html$ netsw-home.cgi [L]
-
-# strip out the subdirs when
-# the browser requests us from perdir pages
-RewriteRule ^.+/(netsw-[^/]+/.+)$ $1 [L]
-
-# and now break the rewriting for local files
-RewriteRule ^netsw-home\.cgi.* - [L]
-RewriteRule ^netsw-changes\.cgi.* - [L]
-RewriteRule ^netsw-search\.cgi.* - [L]
-RewriteRule ^netsw-tree\.cgi$ - [L]
-RewriteRule ^netsw-about\.html$ - [L]
-RewriteRule ^netsw-img/.*$ - [L]
-
-# anything else is a subdir which gets handled
-# by another cgi script
-RewriteRule !^netsw-lsdir\.cgi.* - [C]
-RewriteRule (.*) netsw-lsdir.cgi/$1
-</pre></div>
-
- <p>Some hints for interpretation:</p>
-
- <ol>
- <li>Notice the <code>L</code> (last) flag and no
- substitution field ('<code>-</code>') in the fourth part</li>
-
- <li>Notice the <code>!</code> (not) character and
- the <code>C</code> (chain) flag at the first rule
- in the last part</li>
-
- <li>Notice the catch-all pattern in the last rule</li>
- </ol>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="redirect404" id="redirect404">Redirect Failing URLs to Another Web Server</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>A typical FAQ about URL rewriting is how to redirect
- failing requests on webserver A to webserver B. Usually
- this is done via <code class="directive"><a href="../mod/core.html#errordocument">ErrorDocument</a></code> CGI scripts in Perl, but
- there is also a <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> solution.
- But note that this performs more poorly than using an
- <code class="directive"><a href="../mod/core.html#errordocument">ErrorDocument</a></code>
- CGI script!</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>The first solution has the best performance but less
- flexibility, and is less safe:</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteCond /your/docroot/%{REQUEST_FILENAME} <strong>!-f</strong>
-RewriteRule ^(.+) http://<strong>webserverB</strong>.dom/$1
-</pre></div>
-
- <p>The problem here is that this will only work for pages
- inside the <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>. While you can add more
- Conditions (for instance to also handle homedirs, etc.)
- there is a better variant:</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteCond %{REQUEST_URI} <strong>!-U</strong>
-RewriteRule ^(.+) http://<strong>webserverB</strong>.dom/$1
-</pre></div>
-
- <p>This uses the URL look-ahead feature of <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.
- The result is that this will work for all types of URLs
- and is safe. But it does have a performance impact on
- the web server, because for every request there is one
- more internal subrequest. So, if your web server runs on a
- powerful CPU, use this one. If it is a slow machine, use
- the first approach or better an <code class="directive"><a href="../mod/core.html#errordocument">ErrorDocument</a></code> CGI script.</p>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="archive-access-multiplexer" id="archive-access-multiplexer">Archive Access Multiplexer</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Do you know the great CPAN (Comprehensive Perl Archive
- Network) under <a href="http://www.perl.com/CPAN">http://www.perl.com/CPAN</a>?
- CPAN automatically redirects browsers to one of many FTP
- servers around the world (generally one near the requesting
- client); each server carries a full CPAN mirror. This is
- effectively an FTP access multiplexing service.
- CPAN runs via CGI scripts, but how could a similar approach
- be implemented via <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>First we notice that as of version 3.0.0,
- <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> can
- also use the "<code>ftp:</code>" scheme on redirects.
- And second, the location approximation can be done by a
- <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code>
- over the top-level domain of the client.
- With a tricky chained ruleset we can use this top-level
- domain as a key to our multiplexing map.</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteMap multiplex txt:/path/to/map.cxan
-RewriteRule ^/CxAN/(.*) %{REMOTE_HOST}::$1 [C]
-RewriteRule ^.+\.<strong>([a-zA-Z]+)</strong>::(.*)$ ${multiplex:<strong>$1</strong>|ftp.default.dom}$2 [R,L]
-</pre></div>
-
-<div class="example"><pre>
-##
-## map.cxan -- Multiplexing Map for CxAN
-##
-
-de ftp://ftp.cxan.de/CxAN/
-uk ftp://ftp.cxan.uk/CxAN/
-com ftp://ftp.cxan.com/CxAN/
- :
-##EOF##
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="browser-dependent-content" id="browser-dependent-content">Browser Dependent Content</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>At least for important top-level pages it is sometimes
- necessary to provide the optimum of browser dependent
- content, i.e., one has to provide one version for
- current browsers, a different version for the Lynx and text-mode
- browsers, and another for other browsers.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We cannot use content negotiation because the browsers do
- not provide their type in that form. Instead we have to
- act on the HTTP header "User-Agent". The following config
- does the following: If the HTTP header "User-Agent"
- begins with "Mozilla/3", the page <code>foo.html</code>
- is rewritten to <code>foo.NS.html</code> and the
- rewriting stops. If the browser is "Lynx" or "Mozilla" of
- version 1 or 2, the URL becomes <code>foo.20.html</code>.
- All other browsers receive page <code>foo.32.html</code>.
- This is done with the following ruleset:</p>
-
-<div class="example"><pre>
-RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/3</strong>.*
-RewriteRule ^foo\.html$ foo.<strong>NS</strong>.html [<strong>L</strong>]
-
-RewriteCond %{HTTP_USER_AGENT} ^<strong>Lynx/</strong>.* [OR]
-RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/[12]</strong>.*
-RewriteRule ^foo\.html$ foo.<strong>20</strong>.html [<strong>L</strong>]
-
-RewriteRule ^foo\.html$ foo.<strong>32</strong>.html [<strong>L</strong>]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="dynamic-mirror" id="dynamic-mirror">Dynamic Mirror</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Assume there are nice web pages on remote hosts we want
- to bring into our namespace. For FTP servers we would use
- the <code>mirror</code> program which actually maintains an
- explicit up-to-date copy of the remote data on the local
- machine. For a web server we could use the program
- <code>webcopy</code> which runs via HTTP. But both
- techniques have a major drawback: The local copy is
- always only as up-to-date as the last time we ran the program. It
- would be much better if the mirror was not a static one we
- have to establish explicitly. Instead we want a dynamic
- mirror with data which gets updated automatically
- as needed on the remote host(s).</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>To provide this feature we map the remote web page or even
- the complete remote web area to our namespace by the use
- of the <dfn>Proxy Throughput</dfn> feature
- (flag <code>[P]</code>):</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteRule ^<strong>hotsheet/</strong>(.*)$ <strong>http://www.tstimpreso.com/hotsheet/</strong>$1 [<strong>P</strong>]
-</pre></div>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteRule ^<strong>usa-news\.html</strong>$ <strong>http://www.quux-corp.com/news/index.html</strong> [<strong>P</strong>]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="reverse-dynamic-mirror" id="reverse-dynamic-mirror">Reverse Dynamic Mirror</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>...</dd>
-
- <dt>Solution:</dt>
-
- <dd>
-<div class="example"><pre>
-RewriteEngine on
-RewriteCond /mirror/of/remotesite/$1 -U
-RewriteRule ^http://www\.remotesite\.com/(.*)$ /mirror/of/remotesite/$1
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="retrieve-missing-data" id="retrieve-missing-data">Retrieve Missing Data from Intranet</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>This is a tricky way of virtually running a corporate
- (external) Internet web server
- (<code>www.quux-corp.dom</code>), while actually keeping
- and maintaining its data on an (internal) Intranet web server
- (<code>www2.quux-corp.dom</code>) which is protected by a
- firewall. The trick is that the external web server retrieves
- the requested data on-the-fly from the internal
- one.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>First, we must make sure that our firewall still
- protects the internal web server and only the
- external web server is allowed to retrieve data from it.
- On a packet-filtering firewall, for instance, we could
- configure a firewall ruleset like the following:</p>
-
-<div class="example"><pre>
-<strong>ALLOW</strong> Host www.quux-corp.dom Port >1024 --> Host www2.quux-corp.dom Port <strong>80</strong>
-<strong>DENY</strong> Host * Port * --> Host www2.quux-corp.dom Port <strong>80</strong>
-</pre></div>
-
- <p>Just adjust it to your actual configuration syntax.
- Now we can establish the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
- rules which request the missing data in the background
- through the proxy throughput feature:</p>
-
-<div class="example"><pre>
-RewriteRule ^/~([^/]+)/?(.*) /home/$1/.www/$2
-RewriteCond %{REQUEST_FILENAME} <strong>!-f</strong>
-RewriteCond %{REQUEST_FILENAME} <strong>!-d</strong>
-RewriteRule ^/home/([^/]+)/.www/?(.*) http://<strong>www2</strong>.quux-corp.dom/~$1/pub/$2 [<strong>P</strong>]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="load-balancing" id="load-balancing">Load Balancing</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Suppose we want to load balance the traffic to
- <code>www.example.com</code> over <code>www[0-5].example.com</code>
- (a total of 6 servers). How can this be done?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>There are many possible solutions for this problem.
- We will first discuss a common DNS-based method,
- and then one based on <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>:</p>
-
- <ol>
- <li>
- <strong>DNS Round-Robin</strong>
-
- <p>The simplest method for load-balancing is to use
- DNS round-robin.
- Here you just configure <code>www[0-9].example.com</code>
- as usual in your DNS with A (address) records, e.g.,</p>
-
-<div class="example"><pre>
-www0 IN A 1.2.3.1
-www1 IN A 1.2.3.2
-www2 IN A 1.2.3.3
-www3 IN A 1.2.3.4
-www4 IN A 1.2.3.5
-www5 IN A 1.2.3.6
-</pre></div>
-
- <p>Then you additionally add the following entries:</p>
-
-<div class="example"><pre>
-www IN A 1.2.3.1
-www IN A 1.2.3.2
-www IN A 1.2.3.3
-www IN A 1.2.3.4
-www IN A 1.2.3.5
-</pre></div>
-
- <p>Now when <code>www.example.com</code> gets
- resolved, <code>BIND</code> gives out <code>www0-www5</code>
- - but in a permutated (rotated) order every time.
- This way the clients are spread over the various
- servers. But notice that this is not a perfect load
- balancing scheme, because DNS resolutions are
- cached by clients and other nameservers, so
- once a client has resolved <code>www.example.com</code>
- to a particular <code>wwwN.example.com</code>, all its
- subsequent requests will continue to go to the same
- IP (and thus a single server), rather than being
- distributed across the other available servers. But the
- overall result is
- okay because the requests are collectively
- spread over the various web servers.</p>
- </li>
-
- <li>
- <strong>DNS Load-Balancing</strong>
-
- <p>A sophisticated DNS-based method for
- load-balancing is to use the program
- <code>lbnamed</code> which can be found at <a href="http://www.stanford.edu/~riepel/lbnamed/">
- http://www.stanford.edu/~riepel/lbnamed/</a>.
- It is a Perl 5 program which, in conjunction with auxilliary
- tools, provides real load-balancing via
- DNS.</p>
- </li>
-
- <li>
- <strong>Proxy Throughput Round-Robin</strong>
-
- <p>In this variant we use <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
- and its proxy throughput feature. First we dedicate
- <code>www0.example.com</code> to be actually
- <code>www.example.com</code> by using a single</p>
-
-<div class="example"><pre>
-www IN CNAME www0.example.com.
-</pre></div>
-
- <p>entry in the DNS. Then we convert
- <code>www0.example.com</code> to a proxy-only server,
- i.e., we configure this machine so all arriving URLs
- are simply passed through its internal proxy to one of
- the 5 other servers (<code>www1-www5</code>). To
- accomplish this we first establish a ruleset which
- contacts a load balancing script <code>lb.pl</code>
- for all URLs.</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteMap lb prg:/path/to/lb.pl
-RewriteRule ^/(.+)$ ${lb:$1} [P,L]
-</pre></div>
-
- <p>Then we write <code>lb.pl</code>:</p>
-
-<div class="example"><pre>
-#!/path/to/perl
-##
-## lb.pl -- load balancing script
-##
-
-$| = 1;
-
-$name = "www"; # the hostname base
-$first = 1; # the first server (not 0 here, because 0 is myself)
-$last = 5; # the last server in the round-robin
-$domain = "foo.dom"; # the domainname
-
-$cnt = 0;
-while (<STDIN>) {
- $cnt = (($cnt+1) % ($last+1-$first));
- $server = sprintf("%s%d.%s", $name, $cnt+$first, $domain);
- print "http://$server/$_";
-}
-
-##EOF##
-</pre></div>
-
- <div class="note">A last notice: Why is this useful? Seems like
- <code>www0.example.com</code> still is overloaded? The
- answer is yes, it is overloaded, but with plain proxy
- throughput requests, only! All SSI, CGI, ePerl, etc.
- processing is handled done on the other machines.
- For a complicated site, this may work well. The biggest
- risk here is that www0 is now a single point of failure --
- if it crashes, the other servers are inaccessible.</div>
- </li>
-
- <li>
- <strong>Dedicated Load Balancers</strong>
-
- <p>There are more sophisticated solutions, as well. Cisco,
- F5, and several other companies sell hardware load
- balancers (typically used in pairs for redundancy), which
- offer sophisticated load balancing and auto-failover
- features. There are software packages which offer similar
- features on commodity hardware, as well. If you have
- enough money or need, check these out. The <a href="http://vegan.net/lb/">lb-l mailing list</a> is a
- good place to research.</p>
- </li>
- </ol>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="new-mime-type" id="new-mime-type">New MIME-type, New Service</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>On the net there are many nifty CGI programs. But
- their usage is usually boring, so a lot of webmasters
- don't use them. Even Apache's Action handler feature for
- MIME-types is only appropriate when the CGI programs
- don't need special URLs (actually <code>PATH_INFO</code>
- and <code>QUERY_STRINGS</code>) as their input. First,
- let us configure a new file type with extension
- <code>.scgi</code> (for secure CGI) which will be processed
- by the popular <code>cgiwrap</code> program. The problem
- here is that for instance if we use a Homogeneous URL Layout
- (see above) a file inside the user homedirs might have a URL
- like <code>/u/user/foo/bar.scgi</code>, but
- <code>cgiwrap</code> needs URLs in the form
- <code>/~user/foo/bar.scgi/</code>. The following rule
- solves the problem:</p>
-
-<div class="example"><pre>
-RewriteRule ^/[uge]/<strong>([^/]+)</strong>/\.www/(.+)\.scgi(.*) ...
-... /internal/cgi/user/cgiwrap/~<strong>$1</strong>/$2.scgi$3 [NS,<strong>T=application/x-http-cgi</strong>]
-</pre></div>
-
- <p>Or assume we have some more nifty programs:
- <code>wwwlog</code> (which displays the
- <code>access.log</code> for a URL subtree) and
- <code>wwwidx</code> (which runs Glimpse on a URL
- subtree). We have to provide the URL area to these
- programs so they know which area they are really working with.
- But usually this is complicated, because they may still be
- requested by the alternate URL form, i.e., typically we would
- run the <code>swwidx</code> program from within
- <code>/u/user/foo/</code> via hyperlink to</p>
-
-<div class="example"><pre>
-/internal/cgi/user/swwidx?i=/u/user/foo/
-</pre></div>
-
- <p>which is ugly, because we have to hard-code
- <strong>both</strong> the location of the area
- <strong>and</strong> the location of the CGI inside the
- hyperlink. When we have to reorganize, we spend a
- lot of time changing the various hyperlinks.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>The solution here is to provide a special new URL format
- which automatically leads to the proper CGI invocation.
- We configure the following:</p>
-
-<div class="example"><pre>
-RewriteRule ^/([uge])/([^/]+)(/?.*)/\* /internal/cgi/user/wwwidx?i=/$1/$2$3/
-RewriteRule ^/([uge])/([^/]+)(/?.*):log /internal/cgi/user/wwwlog?f=/$1/$2$3
-</pre></div>
-
- <p>Now the hyperlink to search at
- <code>/u/user/foo/</code> reads only</p>
-
-<div class="example"><pre>
-HREF="*"
-</pre></div>
-
- <p>which internally gets automatically transformed to</p>
-
-<div class="example"><pre>
-/internal/cgi/user/wwwidx?i=/u/user/foo/
-</pre></div>
-
- <p>The same approach leads to an invocation for the
- access log CGI program when the hyperlink
- <code>:log</code> gets used.</p>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="on-the-fly-content" id="on-the-fly-content">On-the-fly Content-Regeneration</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Here comes a really esoteric feature: Dynamically
- generated but statically served pages, i.e., pages should be
- delivered as pure static pages (read from the filesystem
- and just passed through), but they have to be generated
- dynamically by the web server if missing. This way you can
- have CGI-generated pages which are statically served unless an
- admin (or a <code>cron</code> job) removes the static contents. Then the
- contents gets refreshed.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- This is done via the following ruleset:
-
-<div class="example"><pre>
-RewriteCond %{REQUEST_FILENAME} <strong>!-s</strong>
-RewriteRule ^page\.<strong>html</strong>$ page.<strong>cgi</strong> [T=application/x-httpd-cgi,L]
-</pre></div>
-
- <p>Here a request for <code>page.html</code> leads to an
- internal run of a corresponding <code>page.cgi</code> if
- <code>page.html</code> is missing or has filesize
- null. The trick here is that <code>page.cgi</code> is a
- CGI script which (additionally to its <code>STDOUT</code>)
- writes its output to the file <code>page.html</code>.
- Once it has completed, the server sends out
- <code>page.html</code>. When the webmaster wants to force
- a refresh of the contents, he just removes
- <code>page.html</code> (typically from <code>cron</code>).</p>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="autorefresh" id="autorefresh">Document With Autorefresh</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Wouldn't it be nice, while creating a complex web page, if
- the web browser would automatically refresh the page every
- time we save a new version from within our editor?
- Impossible?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>No! We just combine the MIME multipart feature, the
- web server NPH feature, and the URL manipulation power of
- <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. First, we establish a new
- URL feature: Adding just <code>:refresh</code> to any
- URL causes the 'page' to be refreshed every time it is
- updated on the filesystem.</p>
-
-<div class="example"><pre>
-RewriteRule ^(/[uge]/[^/]+/?.*):refresh /internal/cgi/apache/nph-refresh?f=$1
-</pre></div>
-
- <p>Now when we reference the URL</p>
-
-<div class="example"><pre>
-/u/foo/bar/page.html:refresh
-</pre></div>
-
- <p>this leads to the internal invocation of the URL</p>
-
-<div class="example"><pre>
-/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html
-</pre></div>
-
- <p>The only missing part is the NPH-CGI script. Although
- one would usually say "left as an exercise to the reader"
- ;-) I will provide this, too.</p>
-
-<div class="example"><pre>
-#!/sw/bin/perl
-##
-## nph-refresh -- NPH/CGI script for auto refreshing pages
-## Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.
-##
-$| = 1;
-
-# split the QUERY_STRING variable
-@pairs = split(/&/, $ENV{'QUERY_STRING'});
-foreach $pair (@pairs) {
- ($name, $value) = split(/=/, $pair);
- $name =~ tr/A-Z/a-z/;
- $name = 'QS_' . $name;
- $value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
- eval "\$$name = \"$value\"";
-}
-$QS_s = 1 if ($QS_s eq '');
-$QS_n = 3600 if ($QS_n eq '');
-if ($QS_f eq '') {
- print "HTTP/1.0 200 OK\n";
- print "Content-type: text/html\n\n";
- print "&lt;b&gt;ERROR&lt;/b&gt;: No file given\n";
- exit(0);
-}
-if (! -f $QS_f) {
- print "HTTP/1.0 200 OK\n";
- print "Content-type: text/html\n\n";
- print "&lt;b&gt;ERROR&lt;/b&gt;: File $QS_f not found\n";
- exit(0);
-}
-
-sub print_http_headers_multipart_begin {
- print "HTTP/1.0 200 OK\n";
- $bound = "ThisRandomString12345";
- print "Content-type: multipart/x-mixed-replace;boundary=$bound\n";
- &print_http_headers_multipart_next;
-}
-
-sub print_http_headers_multipart_next {
- print "\n--$bound\n";
-}
-
-sub print_http_headers_multipart_end {
- print "\n--$bound--\n";
-}
-
-sub displayhtml {
- local($buffer) = @_;
- $len = length($buffer);
- print "Content-type: text/html\n";
- print "Content-length: $len\n\n";
- print $buffer;
-}
-
-sub readfile {
- local($file) = @_;
- local(*FP, $size, $buffer, $bytes);
- ($x, $x, $x, $x, $x, $x, $x, $size) = stat($file);
- $size = sprintf("%d", $size);
- open(FP, "&lt;$file");
- $bytes = sysread(FP, $buffer, $size);
- close(FP);
- return $buffer;
-}
-
-$buffer = &readfile($QS_f);
-&print_http_headers_multipart_begin;
-&displayhtml($buffer);
-
-sub mystat {
- local($file) = $_[0];
- local($time);
-
- ($x, $x, $x, $x, $x, $x, $x, $x, $x, $mtime) = stat($file);
- return $mtime;
-}
-
-$mtimeL = &mystat($QS_f);
-$mtime = $mtime;
-for ($n = 0; $n &lt; $QS_n; $n++) {
- while (1) {
- $mtime = &mystat($QS_f);
- if ($mtime ne $mtimeL) {
- $mtimeL = $mtime;
- sleep(2);
- $buffer = &readfile($QS_f);
- &print_http_headers_multipart_next;
- &displayhtml($buffer);
- sleep(5);
- $mtimeL = &mystat($QS_f);
- last;
- }
- sleep($QS_s);
- }
-}
-
-&print_http_headers_multipart_end;
-
-exit(0);
-
-##EOF##
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="mass-virtual-hosting" id="mass-virtual-hosting">Mass Virtual Hosting</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>The <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code> feature of Apache is nice
- and works great when you just have a few dozen
- virtual hosts. But when you are an ISP and have hundreds of
- virtual hosts, this feature is suboptimal.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>To provide this feature we map the remote web page or even
- the complete remote web area to our namespace using the
- <dfn>Proxy Throughput</dfn> feature (flag <code>[P]</code>):</p>
-
-<div class="example"><pre>
-##
-## vhost.map
-##
-www.vhost1.dom:80 /path/to/docroot/vhost1
-www.vhost2.dom:80 /path/to/docroot/vhost2
- :
-www.vhostN.dom:80 /path/to/docroot/vhostN
-</pre></div>
-
-<div class="example"><pre>
-##
-## httpd.conf
-##
- :
-# use the canonical hostname on redirects, etc.
-UseCanonicalName on
-
- :
-# add the virtual host in front of the CLF-format
-CustomLog /path/to/access_log "%{VHOST}e %h %l %u %t \"%r\" %>s %b"
- :
-
-# enable the rewriting engine in the main server
-RewriteEngine on
-
-# define two maps: one for fixing the URL and one which defines
-# the available virtual hosts with their corresponding
-# DocumentRoot.
-RewriteMap lowercase int:tolower
-RewriteMap vhost txt:/path/to/vhost.map
-
-# Now do the actual virtual host mapping
-# via a huge and complicated single rule:
-#
-# 1. make sure we don't map for common locations
-RewriteCond %{REQUEST_URI} !^/commonurl1/.*
-RewriteCond %{REQUEST_URI} !^/commonurl2/.*
- :
-RewriteCond %{REQUEST_URI} !^/commonurlN/.*
-#
-# 2. make sure we have a Host header, because
-# currently our approach only supports
-# virtual hosting through this header
-RewriteCond %{HTTP_HOST} !^$
-#
-# 3. lowercase the hostname
-RewriteCond ${lowercase:%{HTTP_HOST}|NONE} ^(.+)$
-#
-# 4. lookup this hostname in vhost.map and
-# remember it only when it is a path
-# (and not "NONE" from above)
-RewriteCond ${vhost:%1} ^(/.*)$
-#
-# 5. finally we can map the URL to its docroot location
-# and remember the virtual host for logging purposes
-RewriteRule ^/(.*)$ %1/$1 [E=VHOST:${lowercase:%{HTTP_HOST}}]
- :
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="host-deny" id="host-deny">Host Deny</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we forbid a list of externally configured hosts
- from using our server?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>For Apache >= 1.3b6:</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteMap hosts-deny txt:/path/to/hosts.deny
-RewriteCond ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND [OR]
-RewriteCond ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND
-RewriteRule ^/.* - [F]
-</pre></div>
-
- <p>For Apache <= 1.3b6:</p>
-
-<div class="example"><pre>
-RewriteEngine on
-RewriteMap hosts-deny txt:/path/to/hosts.deny
-RewriteRule ^/(.*)$ ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND}/$1
-RewriteRule !^NOT-FOUND/.* - [F]
-RewriteRule ^NOT-FOUND/(.*)$ ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND}/$1
-RewriteRule !^NOT-FOUND/.* - [F]
-RewriteRule ^NOT-FOUND/(.*)$ /$1
-</pre></div>
-
-<div class="example"><pre>
-##
-## hosts.deny
-##
-## ATTENTION! This is a map, not a list, even when we treat it as such.
-## mod_rewrite parses it for key/value pairs, so at least a
-## dummy value "-" must be present for each entry.
-##
-
-193.102.180.41 -
-bsdti1.sdm.de -
-192.76.162.40 -
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="proxy-deny" id="proxy-deny">Proxy Deny</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we forbid a certain host or even a user of a
- special host from using the Apache proxy?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We first have to make sure <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
- is below(!) <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> in the Configuration
- file when compiling the Apache web server. This way it gets
- called <em>before</em> <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>. Then we
- configure the following for a host-dependent deny...</p>
-
-<div class="example"><pre>
-RewriteCond %{REMOTE_HOST} <strong>^badhost\.mydomain\.com$</strong>
-RewriteRule !^http://[^/.]\.mydomain.com.* - [F]
-</pre></div>
-
- <p>...and this one for a user@host-dependent deny:</p>
-
-<div class="example"><pre>
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>^badguy@badhost\.mydomain\.com$</strong>
-RewriteRule !^http://[^/.]\.mydomain.com.* - [F]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="special-authentication" id="special-authentication">Special Authentication Variant</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Sometimes very special authentication is needed, for
- instance authentication which checks for a set of
- explicitly configured users. Only these should receive
- access and without explicit prompting (which would occur
- when using Basic Auth via <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code>).</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We use a list of rewrite conditions to exclude all except
- our friends:</p>
-
-<div class="example"><pre>
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend1@client1.quux-corp\.com$</strong>
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend2</strong>@client2.quux-corp\.com$
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend3</strong>@client3.quux-corp\.com$
-RewriteRule ^/~quux/only-for-friends/ - [F]
-</pre></div>
- </dd>
- </dl>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="referer-deflector" id="referer-deflector">Referer-based Deflector</a></h2>
-
-
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we program a flexible URL Deflector which acts
- on the "Referer" HTTP header and can be configured with as
- many referring pages as we like?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>Use the following really tricky ruleset...</p>
-
-<div class="example"><pre>
-RewriteMap deflector txt:/path/to/deflector.map
-
-RewriteCond %{HTTP_REFERER} !=""
-RewriteCond ${deflector:%{HTTP_REFERER}} ^-$
-RewriteRule ^.* %{HTTP_REFERER} [R,L]
-
-RewriteCond %{HTTP_REFERER} !=""
-RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND
-RewriteRule ^.* ${deflector:%{HTTP_REFERER}} [R,L]
-</pre></div>
-
- <p>... in conjunction with a corresponding rewrite
- map:</p>
-
-<div class="example"><pre>
-##
-## deflector.map
-##
-
-http://www.badguys.com/bad/index.html -
-http://www.badguys.com/bad/index2.html -
-http://www.badguys.com/bad/index3.html http://somewhere.com/
-</pre></div>
-
- <p>This automatically redirects the request back to the
- referring page (when "<code>-</code>" is used as the value
- in the map) or to a specific URL (when an URL is specified
- in the map as the second argument).</p>
- </dd>
- </dl>
-
- </div></div>
-<div class="bottomlang">
-<p><span>Available Languages: </span><a href="../en/rewrite/rewrite_guide_advanced.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
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
-<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<!-- $LastChangedRevision$ -->
-
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
-<manualpage metafile="rewrite_guide_advanced.xml.meta">
- <parentdocument href="./">Rewrite</parentdocument>
-
- <title>URL Rewriting Guide - Advanced topics</title>
-
- <summary>
-
- <p>This document supplements the <module>mod_rewrite</module>
- <a href="../mod/mod_rewrite.html">reference documentation</a>.
- It describes how one can use Apache's <module>mod_rewrite</module>
- to solve typical URL-based problems with which webmasters are
- commonly confronted. We give detailed descriptions on how to
- solve each problem by configuring URL rewriting rulesets.</p>
-
- <note type="warning">ATTENTION: Depending on your server configuration
- it may be necessary to adjust the examples for your
- situation, e.g., adding the <code>[PT]</code> flag if
- using <module>mod_alias</module> and
- <module>mod_userdir</module>, etc. Or rewriting a ruleset
- to work in <code>.htaccess</code> context instead
- of per-server context. Always try to understand what a
- particular ruleset really does before you use it; this
- avoids many problems.</note>
-
- </summary>
-<seealso><a href="../mod/mod_rewrite.html">Module
-documentation</a></seealso>
-<seealso><a href="rewrite_intro.html">mod_rewrite
-introduction</a></seealso>
-<seealso><a href="rewrite_guide.html">Rewrite Guide - useful
-examples</a></seealso>
-<seealso><a href="rewrite_tech.html">Technical details</a></seealso>
-
-
- <section id="cluster">
-
- <title>Web Cluster with Consistent URL Space</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>We want to create a homogeneous and consistent URL
- layout across all WWW servers on an Intranet web cluster, i.e.,
- all URLs (by definition server-local and thus
- server-dependent!) become server <em>independent</em>!
- What we want is to give the WWW namespace a single consistent
- layout: no URL should refer to
- any particular target server. The cluster itself
- should connect users automatically to a physical target
- host as needed, invisibly.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>First, the knowledge of the target servers comes from
- (distributed) external maps which contain information on
- where our users, groups, and entities reside. They have the
- form:</p>
-
-<example><pre>
-user1 server_of_user1
-user2 server_of_user2
-: :
-</pre></example>
-
- <p>We put them into files <code>map.xxx-to-host</code>.
- Second we need to instruct all servers to redirect URLs
- of the forms:</p>
-
-<example><pre>
-/u/user/anypath
-/g/group/anypath
-/e/entity/anypath
-</pre></example>
-
- <p>to</p>
-
-<example><pre>
-http://physical-host/u/user/anypath
-http://physical-host/g/group/anypath
-http://physical-host/e/entity/anypath
-</pre></example>
-
- <p>when any URL path need not be valid on every server. The
- following ruleset does this for us with the help of the map
- files (assuming that server0 is a default server which
- will be used if a user has no entry in the map):</p>
-
-<example><pre>
-RewriteEngine on
-
-RewriteMap user-to-host txt:/path/to/map.user-to-host
-RewriteMap group-to-host txt:/path/to/map.group-to-host
-RewriteMap entity-to-host txt:/path/to/map.entity-to-host
-
-RewriteRule ^/u/<strong>([^/]+)</strong>/?(.*) http://<strong>${user-to-host:$1|server0}</strong>/u/$1/$2
-RewriteRule ^/g/<strong>([^/]+)</strong>/?(.*) http://<strong>${group-to-host:$1|server0}</strong>/g/$1/$2
-RewriteRule ^/e/<strong>([^/]+)</strong>/?(.*) http://<strong>${entity-to-host:$1|server0}</strong>/e/$1/$2
-
-RewriteRule ^/([uge])/([^/]+)/?$ /$1/$2/.www/
-RewriteRule ^/([uge])/([^/]+)/([^.]+.+) /$1/$2/.www/$3\
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="structuredhomedirs">
-
- <title>Structured Homedirs</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Some sites with thousands of users use a
- structured homedir layout, <em>i.e.</em> each homedir is in a
- subdirectory which begins (for instance) with the first
- character of the username. So, <code>/~foo/anypath</code>
- is <code>/home/<strong>f</strong>/foo/.www/anypath</code>
- while <code>/~bar/anypath</code> is
- <code>/home/<strong>b</strong>/bar/.www/anypath</code>.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We use the following ruleset to expand the tilde URLs
- into the above layout.</p>
-
-<example><pre>
-RewriteEngine on
-RewriteRule ^/~(<strong>([a-z])</strong>[a-z0-9]+)(.*) /home/<strong>$2</strong>/$1/.www$3
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="filereorg">
-
- <title>Filesystem Reorganization</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>This really is a hardcore example: a killer application
- which heavily uses per-directory
- <code>RewriteRules</code> to get a smooth look and feel
- on the Web while its data structure is never touched or
- adjusted. Background: <strong><em>net.sw</em></strong> is
- my archive of freely available Unix software packages,
- which I started to collect in 1992. It is both my hobby
- and job to do this, because while I'm studying computer
- science I have also worked for many years as a system and
- network administrator in my spare time. Every week I need
- some sort of software so I created a deep hierarchy of
- directories where I stored the packages:</p>
-
-<example><pre>
-drwxrwxr-x 2 netsw users 512 Aug 3 18:39 Audio/
-drwxrwxr-x 2 netsw users 512 Jul 9 14:37 Benchmark/
-drwxrwxr-x 12 netsw users 512 Jul 9 00:34 Crypto/
-drwxrwxr-x 5 netsw users 512 Jul 9 00:41 Database/
-drwxrwxr-x 4 netsw users 512 Jul 30 19:25 Dicts/
-drwxrwxr-x 10 netsw users 512 Jul 9 01:54 Graphic/
-drwxrwxr-x 5 netsw users 512 Jul 9 01:58 Hackers/
-drwxrwxr-x 8 netsw users 512 Jul 9 03:19 InfoSys/
-drwxrwxr-x 3 netsw users 512 Jul 9 03:21 Math/
-drwxrwxr-x 3 netsw users 512 Jul 9 03:24 Misc/
-drwxrwxr-x 9 netsw users 512 Aug 1 16:33 Network/
-drwxrwxr-x 2 netsw users 512 Jul 9 05:53 Office/
-drwxrwxr-x 7 netsw users 512 Jul 9 09:24 SoftEng/
-drwxrwxr-x 7 netsw users 512 Jul 9 12:17 System/
-drwxrwxr-x 12 netsw users 512 Aug 3 20:15 Typesetting/
-drwxrwxr-x 10 netsw users 512 Jul 9 14:08 X11/
-</pre></example>
-
- <p>In July 1996 I decided to make this archive public to
- the world via a nice Web interface. "Nice" means that I
- wanted to offer an interface where you can browse
- directly through the archive hierarchy. And "nice" means
- that I didn't want to change anything inside this
- hierarchy - not even by putting some CGI scripts at the
- top of it. Why? Because the above structure should later be
- accessible via FTP as well, and I didn't want any
- Web or CGI stuff mixed in there.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>The solution has two parts: The first is a set of CGI
- scripts which create all the pages at all directory
- levels on-the-fly. I put them under
- <code>/e/netsw/.www/</code> as follows:</p>
-
-<example><pre>
--rw-r--r-- 1 netsw users 1318 Aug 1 18:10 .wwwacl
-drwxr-xr-x 18 netsw users 512 Aug 5 15:51 DATA/
--rw-rw-rw- 1 netsw users 372982 Aug 5 16:35 LOGFILE
--rw-r--r-- 1 netsw users 659 Aug 4 09:27 TODO
--rw-r--r-- 1 netsw users 5697 Aug 1 18:01 netsw-about.html
--rwxr-xr-x 1 netsw users 579 Aug 2 10:33 netsw-access.pl
--rwxr-xr-x 1 netsw users 1532 Aug 1 17:35 netsw-changes.cgi
--rwxr-xr-x 1 netsw users 2866 Aug 5 14:49 netsw-home.cgi
-drwxr-xr-x 2 netsw users 512 Jul 8 23:47 netsw-img/
--rwxr-xr-x 1 netsw users 24050 Aug 5 15:49 netsw-lsdir.cgi
--rwxr-xr-x 1 netsw users 1589 Aug 3 18:43 netsw-search.cgi
--rwxr-xr-x 1 netsw users 1885 Aug 1 17:41 netsw-tree.cgi
--rw-r--r-- 1 netsw users 234 Jul 30 16:35 netsw-unlimit.lst
-</pre></example>
-
- <p>The <code>DATA/</code> subdirectory holds the above
- directory structure, <em>i.e.</em> the real
- <strong><em>net.sw</em></strong> stuff, and gets
- automatically updated via <code>rdist</code> from time to
- time. The second part of the problem remains: how to link
- these two structures together into one smooth-looking URL
- tree? We want to hide the <code>DATA/</code> directory
- from the user while running the appropriate CGI scripts
- for the various URLs. Here is the solution: first I put
- the following into the per-directory configuration file
- in the <directive module="core">DocumentRoot</directive>
- of the server to rewrite the public URL path
- <code>/net.sw/</code> to the internal path
- <code>/e/netsw</code>:</p>
-
-<example><pre>
-RewriteRule ^net.sw$ net.sw/ [R]
-RewriteRule ^net.sw/(.*)$ e/netsw/$1
-</pre></example>
-
- <p>The first rule is for requests which miss the trailing
- slash! The second rule does the real thing. And then
- comes the killer configuration which stays in the
- per-directory config file
- <code>/e/netsw/.www/.wwwacl</code>:</p>
-
-<example><pre>
-Options ExecCGI FollowSymLinks Includes MultiViews
-
-RewriteEngine on
-
-# we are reached via /net.sw/ prefix
-RewriteBase /net.sw/
-
-# first we rewrite the root dir to
-# the handling cgi script
-RewriteRule ^$ netsw-home.cgi [L]
-RewriteRule ^index\.html$ netsw-home.cgi [L]
-
-# strip out the subdirs when
-# the browser requests us from perdir pages
-RewriteRule ^.+/(netsw-[^/]+/.+)$ $1 [L]
-
-# and now break the rewriting for local files
-RewriteRule ^netsw-home\.cgi.* - [L]
-RewriteRule ^netsw-changes\.cgi.* - [L]
-RewriteRule ^netsw-search\.cgi.* - [L]
-RewriteRule ^netsw-tree\.cgi$ - [L]
-RewriteRule ^netsw-about\.html$ - [L]
-RewriteRule ^netsw-img/.*$ - [L]
-
-# anything else is a subdir which gets handled
-# by another cgi script
-RewriteRule !^netsw-lsdir\.cgi.* - [C]
-RewriteRule (.*) netsw-lsdir.cgi/$1
-</pre></example>
-
- <p>Some hints for interpretation:</p>
-
- <ol>
- <li>Notice the <code>L</code> (last) flag and no
- substitution field ('<code>-</code>') in the fourth part</li>
-
- <li>Notice the <code>!</code> (not) character and
- the <code>C</code> (chain) flag at the first rule
- in the last part</li>
-
- <li>Notice the catch-all pattern in the last rule</li>
- </ol>
- </dd>
- </dl>
-
- </section>
-
- <section id="redirect404">
-
- <title>Redirect Failing URLs to Another Web Server</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>A typical FAQ about URL rewriting is how to redirect
- failing requests on webserver A to webserver B. Usually
- this is done via <directive module="core"
- >ErrorDocument</directive> CGI scripts in Perl, but
- there is also a <module>mod_rewrite</module> solution.
- But note that this performs more poorly than using an
- <directive module="core">ErrorDocument</directive>
- CGI script!</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>The first solution has the best performance but less
- flexibility, and is less safe:</p>
-
-<example><pre>
-RewriteEngine on
-RewriteCond /your/docroot/%{REQUEST_FILENAME} <strong>!-f</strong>
-RewriteRule ^(.+) http://<strong>webserverB</strong>.dom/$1
-</pre></example>
-
- <p>The problem here is that this will only work for pages
- inside the <directive module="core">DocumentRoot</directive>. While you can add more
- Conditions (for instance to also handle homedirs, etc.)
- there is a better variant:</p>
-
-<example><pre>
-RewriteEngine on
-RewriteCond %{REQUEST_URI} <strong>!-U</strong>
-RewriteRule ^(.+) http://<strong>webserverB</strong>.dom/$1
-</pre></example>
-
- <p>This uses the URL look-ahead feature of <module>mod_rewrite</module>.
- The result is that this will work for all types of URLs
- and is safe. But it does have a performance impact on
- the web server, because for every request there is one
- more internal subrequest. So, if your web server runs on a
- powerful CPU, use this one. If it is a slow machine, use
- the first approach or better an <directive module="core"
- >ErrorDocument</directive> CGI script.</p>
- </dd>
- </dl>
-
- </section>
-
- <section id="archive-access-multiplexer">
-
- <title>Archive Access Multiplexer</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Do you know the great CPAN (Comprehensive Perl Archive
- Network) under <a href="http://www.perl.com/CPAN"
- >http://www.perl.com/CPAN</a>?
- CPAN automatically redirects browsers to one of many FTP
- servers around the world (generally one near the requesting
- client); each server carries a full CPAN mirror. This is
- effectively an FTP access multiplexing service.
- CPAN runs via CGI scripts, but how could a similar approach
- be implemented via <module>mod_rewrite</module>?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>First we notice that as of version 3.0.0,
- <module>mod_rewrite</module> can
- also use the "<code>ftp:</code>" scheme on redirects.
- And second, the location approximation can be done by a
- <directive module="mod_rewrite">RewriteMap</directive>
- over the top-level domain of the client.
- With a tricky chained ruleset we can use this top-level
- domain as a key to our multiplexing map.</p>
-
-<example><pre>
-RewriteEngine on
-RewriteMap multiplex txt:/path/to/map.cxan
-RewriteRule ^/CxAN/(.*) %{REMOTE_HOST}::$1 [C]
-RewriteRule ^.+\.<strong>([a-zA-Z]+)</strong>::(.*)$ ${multiplex:<strong>$1</strong>|ftp.default.dom}$2 [R,L]
-</pre></example>
-
-<example><pre>
-##
-## map.cxan -- Multiplexing Map for CxAN
-##
-
-de ftp://ftp.cxan.de/CxAN/
-uk ftp://ftp.cxan.uk/CxAN/
-com ftp://ftp.cxan.com/CxAN/
- :
-##EOF##
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="browser-dependent-content">
-
- <title>Browser Dependent Content</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>At least for important top-level pages it is sometimes
- necessary to provide the optimum of browser dependent
- content, i.e., one has to provide one version for
- current browsers, a different version for the Lynx and text-mode
- browsers, and another for other browsers.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We cannot use content negotiation because the browsers do
- not provide their type in that form. Instead we have to
- act on the HTTP header "User-Agent". The following config
- does the following: If the HTTP header "User-Agent"
- begins with "Mozilla/3", the page <code>foo.html</code>
- is rewritten to <code>foo.NS.html</code> and the
- rewriting stops. If the browser is "Lynx" or "Mozilla" of
- version 1 or 2, the URL becomes <code>foo.20.html</code>.
- All other browsers receive page <code>foo.32.html</code>.
- This is done with the following ruleset:</p>
-
-<example><pre>
-RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/3</strong>.*
-RewriteRule ^foo\.html$ foo.<strong>NS</strong>.html [<strong>L</strong>]
-
-RewriteCond %{HTTP_USER_AGENT} ^<strong>Lynx/</strong>.* [OR]
-RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/[12]</strong>.*
-RewriteRule ^foo\.html$ foo.<strong>20</strong>.html [<strong>L</strong>]
-
-RewriteRule ^foo\.html$ foo.<strong>32</strong>.html [<strong>L</strong>]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="dynamic-mirror">
-
- <title>Dynamic Mirror</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Assume there are nice web pages on remote hosts we want
- to bring into our namespace. For FTP servers we would use
- the <code>mirror</code> program which actually maintains an
- explicit up-to-date copy of the remote data on the local
- machine. For a web server we could use the program
- <code>webcopy</code> which runs via HTTP. But both
- techniques have a major drawback: The local copy is
- always only as up-to-date as the last time we ran the program. It
- would be much better if the mirror was not a static one we
- have to establish explicitly. Instead we want a dynamic
- mirror with data which gets updated automatically
- as needed on the remote host(s).</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>To provide this feature we map the remote web page or even
- the complete remote web area to our namespace by the use
- of the <dfn>Proxy Throughput</dfn> feature
- (flag <code>[P]</code>):</p>
-
-<example><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteRule ^<strong>hotsheet/</strong>(.*)$ <strong>http://www.tstimpreso.com/hotsheet/</strong>$1 [<strong>P</strong>]
-</pre></example>
-
-<example><pre>
-RewriteEngine on
-RewriteBase /~quux/
-RewriteRule ^<strong>usa-news\.html</strong>$ <strong>http://www.quux-corp.com/news/index.html</strong> [<strong>P</strong>]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="reverse-dynamic-mirror">
-
- <title>Reverse Dynamic Mirror</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>...</dd>
-
- <dt>Solution:</dt>
-
- <dd>
-<example><pre>
-RewriteEngine on
-RewriteCond /mirror/of/remotesite/$1 -U
-RewriteRule ^http://www\.remotesite\.com/(.*)$ /mirror/of/remotesite/$1
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="retrieve-missing-data">
-
- <title>Retrieve Missing Data from Intranet</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>This is a tricky way of virtually running a corporate
- (external) Internet web server
- (<code>www.quux-corp.dom</code>), while actually keeping
- and maintaining its data on an (internal) Intranet web server
- (<code>www2.quux-corp.dom</code>) which is protected by a
- firewall. The trick is that the external web server retrieves
- the requested data on-the-fly from the internal
- one.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>First, we must make sure that our firewall still
- protects the internal web server and only the
- external web server is allowed to retrieve data from it.
- On a packet-filtering firewall, for instance, we could
- configure a firewall ruleset like the following:</p>
-
-<example><pre>
-<strong>ALLOW</strong> Host www.quux-corp.dom Port >1024 --> Host www2.quux-corp.dom Port <strong>80</strong>
-<strong>DENY</strong> Host * Port * --> Host www2.quux-corp.dom Port <strong>80</strong>
-</pre></example>
-
- <p>Just adjust it to your actual configuration syntax.
- Now we can establish the <module>mod_rewrite</module>
- rules which request the missing data in the background
- through the proxy throughput feature:</p>
-
-<example><pre>
-RewriteRule ^/~([^/]+)/?(.*) /home/$1/.www/$2
-RewriteCond %{REQUEST_FILENAME} <strong>!-f</strong>
-RewriteCond %{REQUEST_FILENAME} <strong>!-d</strong>
-RewriteRule ^/home/([^/]+)/.www/?(.*) http://<strong>www2</strong>.quux-corp.dom/~$1/pub/$2 [<strong>P</strong>]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="load-balancing">
-
- <title>Load Balancing</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Suppose we want to load balance the traffic to
- <code>www.example.com</code> over <code>www[0-5].example.com</code>
- (a total of 6 servers). How can this be done?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>There are many possible solutions for this problem.
- We will first discuss a common DNS-based method,
- and then one based on <module>mod_rewrite</module>:</p>
-
- <ol>
- <li>
- <strong>DNS Round-Robin</strong>
-
- <p>The simplest method for load-balancing is to use
- DNS round-robin.
- Here you just configure <code>www[0-9].example.com</code>
- as usual in your DNS with A (address) records, e.g.,</p>
-
-<example><pre>
-www0 IN A 1.2.3.1
-www1 IN A 1.2.3.2
-www2 IN A 1.2.3.3
-www3 IN A 1.2.3.4
-www4 IN A 1.2.3.5
-www5 IN A 1.2.3.6
-</pre></example>
-
- <p>Then you additionally add the following entries:</p>
-
-<example><pre>
-www IN A 1.2.3.1
-www IN A 1.2.3.2
-www IN A 1.2.3.3
-www IN A 1.2.3.4
-www IN A 1.2.3.5
-</pre></example>
-
- <p>Now when <code>www.example.com</code> gets
- resolved, <code>BIND</code> gives out <code>www0-www5</code>
- - but in a permutated (rotated) order every time.
- This way the clients are spread over the various
- servers. But notice that this is not a perfect load
- balancing scheme, because DNS resolutions are
- cached by clients and other nameservers, so
- once a client has resolved <code>www.example.com</code>
- to a particular <code>wwwN.example.com</code>, all its
- subsequent requests will continue to go to the same
- IP (and thus a single server), rather than being
- distributed across the other available servers. But the
- overall result is
- okay because the requests are collectively
- spread over the various web servers.</p>
- </li>
-
- <li>
- <strong>DNS Load-Balancing</strong>
-
- <p>A sophisticated DNS-based method for
- load-balancing is to use the program
- <code>lbnamed</code> which can be found at <a
- href="http://www.stanford.edu/~riepel/lbnamed/">
- http://www.stanford.edu/~riepel/lbnamed/</a>.
- It is a Perl 5 program which, in conjunction with auxilliary
- tools, provides real load-balancing via
- DNS.</p>
- </li>
-
- <li>
- <strong>Proxy Throughput Round-Robin</strong>
-
- <p>In this variant we use <module>mod_rewrite</module>
- and its proxy throughput feature. First we dedicate
- <code>www0.example.com</code> to be actually
- <code>www.example.com</code> by using a single</p>
-
-<example><pre>
-www IN CNAME www0.example.com.
-</pre></example>
-
- <p>entry in the DNS. Then we convert
- <code>www0.example.com</code> to a proxy-only server,
- i.e., we configure this machine so all arriving URLs
- are simply passed through its internal proxy to one of
- the 5 other servers (<code>www1-www5</code>). To
- accomplish this we first establish a ruleset which
- contacts a load balancing script <code>lb.pl</code>
- for all URLs.</p>
-
-<example><pre>
-RewriteEngine on
-RewriteMap lb prg:/path/to/lb.pl
-RewriteRule ^/(.+)$ ${lb:$1} [P,L]
-</pre></example>
-
- <p>Then we write <code>lb.pl</code>:</p>
-
-<example><pre>
-#!/path/to/perl
-##
-## lb.pl -- load balancing script
-##
-
-$| = 1;
-
-$name = "www"; # the hostname base
-$first = 1; # the first server (not 0 here, because 0 is myself)
-$last = 5; # the last server in the round-robin
-$domain = "foo.dom"; # the domainname
-
-$cnt = 0;
-while (<STDIN>) {
- $cnt = (($cnt+1) % ($last+1-$first));
- $server = sprintf("%s%d.%s", $name, $cnt+$first, $domain);
- print "http://$server/$_";
-}
-
-##EOF##
-</pre></example>
-
- <note>A last notice: Why is this useful? Seems like
- <code>www0.example.com</code> still is overloaded? The
- answer is yes, it is overloaded, but with plain proxy
- throughput requests, only! All SSI, CGI, ePerl, etc.
- processing is handled done on the other machines.
- For a complicated site, this may work well. The biggest
- risk here is that www0 is now a single point of failure --
- if it crashes, the other servers are inaccessible.</note>
- </li>
-
- <li>
- <strong>Dedicated Load Balancers</strong>
-
- <p>There are more sophisticated solutions, as well. Cisco,
- F5, and several other companies sell hardware load
- balancers (typically used in pairs for redundancy), which
- offer sophisticated load balancing and auto-failover
- features. There are software packages which offer similar
- features on commodity hardware, as well. If you have
- enough money or need, check these out. The <a
- href="http://vegan.net/lb/">lb-l mailing list</a> is a
- good place to research.</p>
- </li>
- </ol>
- </dd>
- </dl>
-
- </section>
-
- <section id="new-mime-type">
-
- <title>New MIME-type, New Service</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>On the net there are many nifty CGI programs. But
- their usage is usually boring, so a lot of webmasters
- don't use them. Even Apache's Action handler feature for
- MIME-types is only appropriate when the CGI programs
- don't need special URLs (actually <code>PATH_INFO</code>
- and <code>QUERY_STRINGS</code>) as their input. First,
- let us configure a new file type with extension
- <code>.scgi</code> (for secure CGI) which will be processed
- by the popular <code>cgiwrap</code> program. The problem
- here is that for instance if we use a Homogeneous URL Layout
- (see above) a file inside the user homedirs might have a URL
- like <code>/u/user/foo/bar.scgi</code>, but
- <code>cgiwrap</code> needs URLs in the form
- <code>/~user/foo/bar.scgi/</code>. The following rule
- solves the problem:</p>
-
-<example><pre>
-RewriteRule ^/[uge]/<strong>([^/]+)</strong>/\.www/(.+)\.scgi(.*) ...
-... /internal/cgi/user/cgiwrap/~<strong>$1</strong>/$2.scgi$3 [NS,<strong>T=application/x-http-cgi</strong>]
-</pre></example>
-
- <p>Or assume we have some more nifty programs:
- <code>wwwlog</code> (which displays the
- <code>access.log</code> for a URL subtree) and
- <code>wwwidx</code> (which runs Glimpse on a URL
- subtree). We have to provide the URL area to these
- programs so they know which area they are really working with.
- But usually this is complicated, because they may still be
- requested by the alternate URL form, i.e., typically we would
- run the <code>swwidx</code> program from within
- <code>/u/user/foo/</code> via hyperlink to</p>
-
-<example><pre>
-/internal/cgi/user/swwidx?i=/u/user/foo/
-</pre></example>
-
- <p>which is ugly, because we have to hard-code
- <strong>both</strong> the location of the area
- <strong>and</strong> the location of the CGI inside the
- hyperlink. When we have to reorganize, we spend a
- lot of time changing the various hyperlinks.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>The solution here is to provide a special new URL format
- which automatically leads to the proper CGI invocation.
- We configure the following:</p>
-
-<example><pre>
-RewriteRule ^/([uge])/([^/]+)(/?.*)/\* /internal/cgi/user/wwwidx?i=/$1/$2$3/
-RewriteRule ^/([uge])/([^/]+)(/?.*):log /internal/cgi/user/wwwlog?f=/$1/$2$3
-</pre></example>
-
- <p>Now the hyperlink to search at
- <code>/u/user/foo/</code> reads only</p>
-
-<example><pre>
-HREF="*"
-</pre></example>
-
- <p>which internally gets automatically transformed to</p>
-
-<example><pre>
-/internal/cgi/user/wwwidx?i=/u/user/foo/
-</pre></example>
-
- <p>The same approach leads to an invocation for the
- access log CGI program when the hyperlink
- <code>:log</code> gets used.</p>
- </dd>
- </dl>
-
- </section>
-
- <section id="on-the-fly-content">
-
- <title>On-the-fly Content-Regeneration</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Here comes a really esoteric feature: Dynamically
- generated but statically served pages, i.e., pages should be
- delivered as pure static pages (read from the filesystem
- and just passed through), but they have to be generated
- dynamically by the web server if missing. This way you can
- have CGI-generated pages which are statically served unless an
- admin (or a <code>cron</code> job) removes the static contents. Then the
- contents gets refreshed.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- This is done via the following ruleset:
-
-<example><pre>
-RewriteCond %{REQUEST_FILENAME} <strong>!-s</strong>
-RewriteRule ^page\.<strong>html</strong>$ page.<strong>cgi</strong> [T=application/x-httpd-cgi,L]
-</pre></example>
-
- <p>Here a request for <code>page.html</code> leads to an
- internal run of a corresponding <code>page.cgi</code> if
- <code>page.html</code> is missing or has filesize
- null. The trick here is that <code>page.cgi</code> is a
- CGI script which (additionally to its <code>STDOUT</code>)
- writes its output to the file <code>page.html</code>.
- Once it has completed, the server sends out
- <code>page.html</code>. When the webmaster wants to force
- a refresh of the contents, he just removes
- <code>page.html</code> (typically from <code>cron</code>).</p>
- </dd>
- </dl>
-
- </section>
-
- <section id="autorefresh">
-
- <title>Document With Autorefresh</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Wouldn't it be nice, while creating a complex web page, if
- the web browser would automatically refresh the page every
- time we save a new version from within our editor?
- Impossible?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>No! We just combine the MIME multipart feature, the
- web server NPH feature, and the URL manipulation power of
- <module>mod_rewrite</module>. First, we establish a new
- URL feature: Adding just <code>:refresh</code> to any
- URL causes the 'page' to be refreshed every time it is
- updated on the filesystem.</p>
-
-<example><pre>
-RewriteRule ^(/[uge]/[^/]+/?.*):refresh /internal/cgi/apache/nph-refresh?f=$1
-</pre></example>
-
- <p>Now when we reference the URL</p>
-
-<example><pre>
-/u/foo/bar/page.html:refresh
-</pre></example>
-
- <p>this leads to the internal invocation of the URL</p>
-
-<example><pre>
-/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html
-</pre></example>
-
- <p>The only missing part is the NPH-CGI script. Although
- one would usually say "left as an exercise to the reader"
- ;-) I will provide this, too.</p>
-
-<example><pre>
-#!/sw/bin/perl
-##
-## nph-refresh -- NPH/CGI script for auto refreshing pages
-## Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.
-##
-$| = 1;
-
-# split the QUERY_STRING variable
-@pairs = split(/&/, $ENV{'QUERY_STRING'});
-foreach $pair (@pairs) {
- ($name, $value) = split(/=/, $pair);
- $name =~ tr/A-Z/a-z/;
- $name = 'QS_' . $name;
- $value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
- eval "\$$name = \"$value\"";
-}
-$QS_s = 1 if ($QS_s eq '');
-$QS_n = 3600 if ($QS_n eq '');
-if ($QS_f eq '') {
- print "HTTP/1.0 200 OK\n";
- print "Content-type: text/html\n\n";
- print "&lt;b&gt;ERROR&lt;/b&gt;: No file given\n";
- exit(0);
-}
-if (! -f $QS_f) {
- print "HTTP/1.0 200 OK\n";
- print "Content-type: text/html\n\n";
- print "&lt;b&gt;ERROR&lt;/b&gt;: File $QS_f not found\n";
- exit(0);
-}
-
-sub print_http_headers_multipart_begin {
- print "HTTP/1.0 200 OK\n";
- $bound = "ThisRandomString12345";
- print "Content-type: multipart/x-mixed-replace;boundary=$bound\n";
- &print_http_headers_multipart_next;
-}
-
-sub print_http_headers_multipart_next {
- print "\n--$bound\n";
-}
-
-sub print_http_headers_multipart_end {
- print "\n--$bound--\n";
-}
-
-sub displayhtml {
- local($buffer) = @_;
- $len = length($buffer);
- print "Content-type: text/html\n";
- print "Content-length: $len\n\n";
- print $buffer;
-}
-
-sub readfile {
- local($file) = @_;
- local(*FP, $size, $buffer, $bytes);
- ($x, $x, $x, $x, $x, $x, $x, $size) = stat($file);
- $size = sprintf("%d", $size);
- open(FP, "&lt;$file");
- $bytes = sysread(FP, $buffer, $size);
- close(FP);
- return $buffer;
-}
-
-$buffer = &readfile($QS_f);
-&print_http_headers_multipart_begin;
-&displayhtml($buffer);
-
-sub mystat {
- local($file) = $_[0];
- local($time);
-
- ($x, $x, $x, $x, $x, $x, $x, $x, $x, $mtime) = stat($file);
- return $mtime;
-}
-
-$mtimeL = &mystat($QS_f);
-$mtime = $mtime;
-for ($n = 0; $n &lt; $QS_n; $n++) {
- while (1) {
- $mtime = &mystat($QS_f);
- if ($mtime ne $mtimeL) {
- $mtimeL = $mtime;
- sleep(2);
- $buffer = &readfile($QS_f);
- &print_http_headers_multipart_next;
- &displayhtml($buffer);
- sleep(5);
- $mtimeL = &mystat($QS_f);
- last;
- }
- sleep($QS_s);
- }
-}
-
-&print_http_headers_multipart_end;
-
-exit(0);
-
-##EOF##
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="mass-virtual-hosting">
-
- <title>Mass Virtual Hosting</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>The <directive type="section" module="core"
- >VirtualHost</directive> feature of Apache is nice
- and works great when you just have a few dozen
- virtual hosts. But when you are an ISP and have hundreds of
- virtual hosts, this feature is suboptimal.</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>To provide this feature we map the remote web page or even
- the complete remote web area to our namespace using the
- <dfn>Proxy Throughput</dfn> feature (flag <code>[P]</code>):</p>
-
-<example><pre>
-##
-## vhost.map
-##
-www.vhost1.dom:80 /path/to/docroot/vhost1
-www.vhost2.dom:80 /path/to/docroot/vhost2
- :
-www.vhostN.dom:80 /path/to/docroot/vhostN
-</pre></example>
-
-<example><pre>
-##
-## httpd.conf
-##
- :
-# use the canonical hostname on redirects, etc.
-UseCanonicalName on
-
- :
-# add the virtual host in front of the CLF-format
-CustomLog /path/to/access_log "%{VHOST}e %h %l %u %t \"%r\" %>s %b"
- :
-
-# enable the rewriting engine in the main server
-RewriteEngine on
-
-# define two maps: one for fixing the URL and one which defines
-# the available virtual hosts with their corresponding
-# DocumentRoot.
-RewriteMap lowercase int:tolower
-RewriteMap vhost txt:/path/to/vhost.map
-
-# Now do the actual virtual host mapping
-# via a huge and complicated single rule:
-#
-# 1. make sure we don't map for common locations
-RewriteCond %{REQUEST_URI} !^/commonurl1/.*
-RewriteCond %{REQUEST_URI} !^/commonurl2/.*
- :
-RewriteCond %{REQUEST_URI} !^/commonurlN/.*
-#
-# 2. make sure we have a Host header, because
-# currently our approach only supports
-# virtual hosting through this header
-RewriteCond %{HTTP_HOST} !^$
-#
-# 3. lowercase the hostname
-RewriteCond ${lowercase:%{HTTP_HOST}|NONE} ^(.+)$
-#
-# 4. lookup this hostname in vhost.map and
-# remember it only when it is a path
-# (and not "NONE" from above)
-RewriteCond ${vhost:%1} ^(/.*)$
-#
-# 5. finally we can map the URL to its docroot location
-# and remember the virtual host for logging purposes
-RewriteRule ^/(.*)$ %1/$1 [E=VHOST:${lowercase:%{HTTP_HOST}}]
- :
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="host-deny">
-
- <title>Host Deny</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we forbid a list of externally configured hosts
- from using our server?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>For Apache >= 1.3b6:</p>
-
-<example><pre>
-RewriteEngine on
-RewriteMap hosts-deny txt:/path/to/hosts.deny
-RewriteCond ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND [OR]
-RewriteCond ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND
-RewriteRule ^/.* - [F]
-</pre></example>
-
- <p>For Apache <= 1.3b6:</p>
-
-<example><pre>
-RewriteEngine on
-RewriteMap hosts-deny txt:/path/to/hosts.deny
-RewriteRule ^/(.*)$ ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND}/$1
-RewriteRule !^NOT-FOUND/.* - [F]
-RewriteRule ^NOT-FOUND/(.*)$ ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND}/$1
-RewriteRule !^NOT-FOUND/.* - [F]
-RewriteRule ^NOT-FOUND/(.*)$ /$1
-</pre></example>
-
-<example><pre>
-##
-## hosts.deny
-##
-## ATTENTION! This is a map, not a list, even when we treat it as such.
-## mod_rewrite parses it for key/value pairs, so at least a
-## dummy value "-" must be present for each entry.
-##
-
-193.102.180.41 -
-bsdti1.sdm.de -
-192.76.162.40 -
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="proxy-deny">
-
- <title>Proxy Deny</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we forbid a certain host or even a user of a
- special host from using the Apache proxy?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We first have to make sure <module>mod_rewrite</module>
- is below(!) <module>mod_proxy</module> in the Configuration
- file when compiling the Apache web server. This way it gets
- called <em>before</em> <module>mod_proxy</module>. Then we
- configure the following for a host-dependent deny...</p>
-
-<example><pre>
-RewriteCond %{REMOTE_HOST} <strong>^badhost\.mydomain\.com$</strong>
-RewriteRule !^http://[^/.]\.mydomain.com.* - [F]
-</pre></example>
-
- <p>...and this one for a user@host-dependent deny:</p>
-
-<example><pre>
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>^badguy@badhost\.mydomain\.com$</strong>
-RewriteRule !^http://[^/.]\.mydomain.com.* - [F]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="special-authentication">
-
- <title>Special Authentication Variant</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>Sometimes very special authentication is needed, for
- instance authentication which checks for a set of
- explicitly configured users. Only these should receive
- access and without explicit prompting (which would occur
- when using Basic Auth via <module>mod_auth_basic</module>).</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>We use a list of rewrite conditions to exclude all except
- our friends:</p>
-
-<example><pre>
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend1@client1.quux-corp\.com$</strong>
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend2</strong>@client2.quux-corp\.com$
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend3</strong>@client3.quux-corp\.com$
-RewriteRule ^/~quux/only-for-friends/ - [F]
-</pre></example>
- </dd>
- </dl>
-
- </section>
-
- <section id="referer-deflector">
-
- <title>Referer-based Deflector</title>
-
- <dl>
- <dt>Description:</dt>
-
- <dd>
- <p>How can we program a flexible URL Deflector which acts
- on the "Referer" HTTP header and can be configured with as
- many referring pages as we like?</p>
- </dd>
-
- <dt>Solution:</dt>
-
- <dd>
- <p>Use the following really tricky ruleset...</p>
-
-<example><pre>
-RewriteMap deflector txt:/path/to/deflector.map
-
-RewriteCond %{HTTP_REFERER} !=""
-RewriteCond ${deflector:%{HTTP_REFERER}} ^-$
-RewriteRule ^.* %{HTTP_REFERER} [R,L]
-
-RewriteCond %{HTTP_REFERER} !=""
-RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND
-RewriteRule ^.* ${deflector:%{HTTP_REFERER}} [R,L]
-</pre></example>
-
- <p>... in conjunction with a corresponding rewrite
- map:</p>
-
-<example><pre>
-##
-## deflector.map
-##
-
-http://www.badguys.com/bad/index.html -
-http://www.badguys.com/bad/index2.html -
-http://www.badguys.com/bad/index3.html http://somewhere.com/
-</pre></example>
-
- <p>This automatically redirects the request back to the
- referring page (when "<code>-</code>" is used as the value
- in the map) or to a specific URL (when an URL is specified
- in the map as the second argument).</p>
- </dd>
- </dl>
-
- </section>
-
-</manualpage>
-
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" ?>
-<!-- GENERATED FROM XML: DO NOT EDIT -->
-
-<metafile reference="rewrite_guide_advanced.xml">
- <basename>rewrite_guide_advanced</basename>
- <path>/rewrite/</path>
- <relpath>..</relpath>
-
- <variants>
- <variant>en</variant>
- </variants>
-</metafile>
--- /dev/null
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: rewritemap.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1
--- /dev/null
+<?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
--- /dev/null
+<?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>
--- /dev/null
+<?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>
# GENERATED FROM XML -- DO NOT EDIT
-URI: rewrite_guide_advanced.html.en
+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
<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/rewrite_tech.html" title="English"> en </a></p>
+<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
<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="rewrite_intro.html">mod_rewrite
-introduction</a></li><li><a href="rewrite_guide.html">Rewrite Guide - useful
-examples</a></li><li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide -
-advanced useful examples</a></li></ul></div>
+</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>
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/mod_rewrite_fig1.gif" width="428" height="385" alt="[Needs graphics capability to display]" /><br />
+ <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
</div></div>
<div class="bottomlang">
-<p><span>Available Languages: </span><a href="../en/rewrite/rewrite_tech.html" title="English"> en </a></p>
+<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>
--- /dev/null
+<?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
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<!-- $LastChangedRevision$ -->
+<!-- $LastChangedRevision: 945974 $ -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
limitations under the License.
-->
-<manualpage metafile="rewrite_tech.xml.meta">
+<manualpage metafile="tech.xml.meta">
<parentdocument href="./">Rewrite</parentdocument>
<title>Apache mod_rewrite Technical Details</title>
<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="rewrite_intro.html">mod_rewrite
-introduction</a></seealso>
-<seealso><a href="rewrite_guide.html">Rewrite Guide - useful
-examples</a></seealso>
-<seealso><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide -
-advanced useful examples</a></seealso>
+<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>
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/mod_rewrite_fig1.gif" width="428"
- height="385" alt="[Needs graphics capability to display]" /><br />
+ <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
--- /dev/null
+<?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>
+
--- /dev/null
+<?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>
--- /dev/null
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: vhosts.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1
--- /dev/null
+<?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>Dynamic mass virtual hosts with mod_rewrite - 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>Dynamic mass virtual hosts with mod_rewrite</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/rewrite/vhosts.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
+how you can use <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to create dynamically
+configured virtual hosts.</p>
+
+<div class="warning">mod_rewrite is not the best way to configure
+virtual hosts. You should first consider the <a href="../vhosts/mass.html">alternatives</a> before resorting to
+mod_rewrite. See also the "<a href="avoid.html#vhosts">how to avoid
+mod_rewrite</a> document.</div>
+
+</div>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#per-hostname">Virtual Hosts For Arbitrary Hostnames</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#simple.rewrite">Dynamic
+ Virtual Hosts Using <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code></a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#xtra-conf">Using a Separate Virtual Host Configuration File</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="proxy.html">Proxying</a></li><li><a href="rewritemap.html">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="per-hostname" id="per-hostname">Virtual Hosts For Arbitrary Hostnames</a></h2>
+
+
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We want to automatically create a virtual host for every hostname
+ which resolves in our domain, without having to create
+ new VirtualHost sections.</p>
+
+ <p>In this recipe, we assume that we'll be using the hostname
+ <code>www.<strong>SITE</strong>.example.com</code> for each
+ user, and serve their content out of
+ <code>/home/<strong>SITE</strong>/www</code>.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+<br />
+RewriteMap lowercase int:tolower<br />
+<br />
+RewriteCond %{lowercase:%{<strong>HTTP_HOST</strong>}} ^www\.<strong>([^.]+)</strong>\.example\.com$<br />
+RewriteRule ^(.*) /home/<strong>%1</strong>/www$1
+</code></p></div></dd>
+
+<dt>Discussion</dt>
+ <dd>
+
+ <div class="warning">You will need to take care of the DNS
+ resolution - Apache does
+ not handle name resolution. You'll need either to create CNAME
+ records for each hostname, or a DNS wildcard record. Creating DNS
+ records is beyond the scope of this document.</div>
+
+<p>The internal <code>tolower</code> RewriteMap directive is used to
+ensure that the hostnames being used are all lowercase, so that there is
+no ambiguity in the directory structure which must be created.</p>
+
+<p>Parentheses used in a <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> are captured into the
+backreferences <code>%1</code>, <code>%2</code>, etc, while parentheses
+used in <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> are
+captured into the backreferences <code>$1</code>, <code>$2</code>,
+etc.</p>
+
+<p>
+As with many techniques discussed in this document, mod_rewrite really
+isn't the best way to accomplish this task. You should, instead,
+consider using <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> instead, as it will much
+more gracefully handle anything beyond serving static files, such as any
+dynamic content, and Alias resolution.
+</p>
+ </dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="simple.rewrite" id="simple.rewrite">Dynamic
+ Virtual Hosts Using <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code></a></h2>
+
+ <p>This extract from <code>httpd.conf</code> does the same
+ thing as <a href="#simple">the first example</a>. The first
+ half is very similar to the corresponding part above, except for
+ some changes, required for backward compatibility and to make the
+ <code>mod_rewrite</code> part work properly; the second half
+ configures <code>mod_rewrite</code> to do the actual work.</p>
+
+ <p>Because <code>mod_rewrite</code> runs before other URI translation
+ modules (e.g., <code>mod_alias</code>), <code>mod_rewrite</code> must
+ be told to explicitly ignore any URLs that would have been handled
+ by those modules. And, because these rules would otherwise bypass
+ any <code>ScriptAlias</code> directives, we must have
+ <code>mod_rewrite</code> explicitly enact those mappings.</p>
+
+<div class="example"><p><code>
+# get the server name from the Host: header<br />
+UseCanonicalName Off<br />
+<br />
+# splittable logs<br />
+LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon<br />
+CustomLog logs/access_log vcommon<br />
+<br />
+<Directory /www/hosts><br />
+<span class="indent">
+ # ExecCGI is needed here because we can't force<br />
+ # CGI execution in the way that ScriptAlias does<br />
+ Options FollowSymLinks ExecCGI<br />
+</span>
+</Directory><br />
+<br />
+RewriteEngine On<br />
+<br />
+# a ServerName derived from a Host: header may be any case at all<br />
+RewriteMap lowercase int:tolower<br />
+<br />
+## deal with normal documents first:<br />
+# allow Alias /icons/ to work - repeat for other aliases<br />
+RewriteCond %{REQUEST_URI} !^/icons/<br />
+# allow CGIs to work<br />
+RewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
+# do the magic<br />
+RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1<br />
+<br />
+## and now deal with CGIs - we have to force a handler<br />
+RewriteCond %{REQUEST_URI} ^/cgi-bin/<br />
+RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [H=cgi-script]<br />
+</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="xtra-conf" id="xtra-conf">Using a Separate Virtual Host Configuration File</a></h2>
+
+ <p>This arrangement uses more advanced <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+ features to work out the translation from virtual host to document
+ root, from a separate configuration file. This provides more
+ flexibility, but requires more complicated configuration.</p>
+
+ <p>The <code>vhost.map</code> file should look something like
+ this:</p>
+
+<div class="example"><p><code>
+customer-1.example.com /www/customers/1<br />
+customer-2.example.com /www/customers/2<br />
+# ...<br />
+customer-N.example.com /www/customers/N<br />
+</code></p></div>
+
+ <p>The <code>httpd.conf</code> should contain the following:</p>
+
+<div class="example"><p><code>
+RewriteEngine on<br />
+<br />
+RewriteMap lowercase int:tolower<br />
+<br />
+# define the map file<br />
+RewriteMap vhost txt:/www/conf/vhost.map<br />
+<br />
+# deal with aliases as above<br />
+RewriteCond %{REQUEST_URI} !^/icons/<br />
+RewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
+RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br />
+# this does the file-based remap<br />
+RewriteCond ${vhost:%1} ^(/.*)$<br />
+RewriteRule ^/(.*)$ %1/docs/$1<br />
+<br />
+RewriteCond %{REQUEST_URI} ^/cgi-bin/<br />
+RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br />
+RewriteCond ${vhost:%1} ^(/.*)$<br />
+RewriteRule ^/(.*)$ %1/cgi-bin/$1 [H=cgi-script]
+</code></p></div>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/vhosts.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
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 1059165 $ -->
+
+<!--
+ 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="vhosts.xml.meta">
+ <parentdocument href="./">Rewrite</parentdocument>
+
+<title>Dynamic mass virtual hosts with mod_rewrite</title>
+
+<summary>
+
+<p>This document supplements the <module>mod_rewrite</module>
+<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
+how you can use <module>mod_rewrite</module> to create dynamically
+configured virtual hosts.</p>
+
+<note type="warning">mod_rewrite is not the best way to configure
+virtual hosts. You should first consider the <a
+href="../vhosts/mass.html">alternatives</a> before resorting to
+mod_rewrite. See also the "<a href="avoid.html#vhosts">how to avoid
+mod_rewrite</a> document.</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="rewritemap.html">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="per-hostname">
+
+ <title>Virtual Hosts For Arbitrary Hostnames</title>
+
+ <dl>
+ <dt>Description:</dt>
+
+ <dd>
+ <p>We want to automatically create a virtual host for every hostname
+ which resolves in our domain, without having to create
+ new VirtualHost sections.</p>
+
+ <p>In this recipe, we assume that we'll be using the hostname
+ <code>www.<strong>SITE</strong>.example.com</code> for each
+ user, and serve their content out of
+ <code>/home/<strong>SITE</strong>/www</code>.</p>
+ </dd>
+
+ <dt>Solution:</dt>
+
+ <dd>
+
+<example>
+RewriteEngine on<br />
+<br />
+RewriteMap lowercase int:tolower<br />
+<br />
+RewriteCond %{lowercase:%{<strong>HTTP_HOST</strong>}} ^www\.<strong>([^.]+)</strong>\.example\.com$<br />
+RewriteRule ^(.*) /home/<strong>%1</strong>/www$1
+</example></dd>
+
+<dt>Discussion</dt>
+ <dd>
+
+ <note type="warning">You will need to take care of the DNS
+ resolution - Apache does
+ not handle name resolution. You'll need either to create CNAME
+ records for each hostname, or a DNS wildcard record. Creating DNS
+ records is beyond the scope of this document.</note>
+
+<p>The internal <code>tolower</code> RewriteMap directive is used to
+ensure that the hostnames being used are all lowercase, so that there is
+no ambiguity in the directory structure which must be created.</p>
+
+<p>Parentheses used in a <directive
+module="mod_rewrite">RewriteCond</directive> are captured into the
+backreferences <code>%1</code>, <code>%2</code>, etc, while parentheses
+used in <directive module="mod_rewrite">RewriteRule</directive> are
+captured into the backreferences <code>$1</code>, <code>$2</code>,
+etc.</p>
+
+<p>
+As with many techniques discussed in this document, mod_rewrite really
+isn't the best way to accomplish this task. You should, instead,
+consider using <module>mod_vhost_alias</module> instead, as it will much
+more gracefully handle anything beyond serving static files, such as any
+dynamic content, and Alias resolution.
+</p>
+ </dd>
+ </dl>
+
+</section>
+
+<section id="simple.rewrite"><title>Dynamic
+ Virtual Hosts Using <module>mod_rewrite</module></title>
+
+ <p>This extract from <code>httpd.conf</code> does the same
+ thing as <a href="#simple">the first example</a>. The first
+ half is very similar to the corresponding part above, except for
+ some changes, required for backward compatibility and to make the
+ <code>mod_rewrite</code> part work properly; the second half
+ configures <code>mod_rewrite</code> to do the actual work.</p>
+
+ <p>Because <code>mod_rewrite</code> runs before other URI translation
+ modules (e.g., <code>mod_alias</code>), <code>mod_rewrite</code> must
+ be told to explicitly ignore any URLs that would have been handled
+ by those modules. And, because these rules would otherwise bypass
+ any <code>ScriptAlias</code> directives, we must have
+ <code>mod_rewrite</code> explicitly enact those mappings.</p>
+
+<example>
+# get the server name from the Host: header<br />
+UseCanonicalName Off<br />
+<br />
+# splittable logs<br />
+LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon<br />
+CustomLog logs/access_log vcommon<br />
+<br />
+<Directory /www/hosts><br />
+<indent>
+ # ExecCGI is needed here because we can't force<br />
+ # CGI execution in the way that ScriptAlias does<br />
+ Options FollowSymLinks ExecCGI<br />
+</indent>
+</Directory><br />
+<br />
+RewriteEngine On<br />
+<br />
+# a ServerName derived from a Host: header may be any case at all<br />
+RewriteMap lowercase int:tolower<br />
+<br />
+## deal with normal documents first:<br />
+# allow Alias /icons/ to work - repeat for other aliases<br />
+RewriteCond %{REQUEST_URI} !^/icons/<br />
+# allow CGIs to work<br />
+RewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
+# do the magic<br />
+RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1<br />
+<br />
+## and now deal with CGIs - we have to force a handler<br />
+RewriteCond %{REQUEST_URI} ^/cgi-bin/<br />
+RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [H=cgi-script]<br />
+</example>
+
+</section>
+
+<section id="xtra-conf"><title>Using a Separate Virtual Host Configuration File</title>
+
+ <p>This arrangement uses more advanced <module>mod_rewrite</module>
+ features to work out the translation from virtual host to document
+ root, from a separate configuration file. This provides more
+ flexibility, but requires more complicated configuration.</p>
+
+ <p>The <code>vhost.map</code> file should look something like
+ this:</p>
+
+<example>
+customer-1.example.com /www/customers/1<br />
+customer-2.example.com /www/customers/2<br />
+# ...<br />
+customer-N.example.com /www/customers/N<br />
+</example>
+
+ <p>The <code>httpd.conf</code> should contain the following:</p>
+
+<example>
+RewriteEngine on<br />
+<br />
+RewriteMap lowercase int:tolower<br />
+<br />
+# define the map file<br />
+RewriteMap vhost txt:/www/conf/vhost.map<br />
+<br />
+# deal with aliases as above<br />
+RewriteCond %{REQUEST_URI} !^/icons/<br />
+RewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
+RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br />
+# this does the file-based remap<br />
+RewriteCond ${vhost:%1} ^(/.*)$<br />
+RewriteRule ^/(.*)$ %1/docs/$1<br />
+<br />
+RewriteCond %{REQUEST_URI} ^/cgi-bin/<br />
+RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br />
+RewriteCond ${vhost:%1} ^(/.*)$<br />
+RewriteRule ^/(.*)$ %1/cgi-bin/$1 [H=cgi-script]
+</example>
+
+</section>
+
+</manualpage>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- GENERATED FROM XML: DO NOT EDIT -->
+
+<metafile reference="vhosts.xml">
+ <basename>vhosts</basename>
+ <path>/rewrite/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
projects / thirdparty / apache / httpd.git / commitdiff
