httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rbo...@apache.org
Subject svn commit: r157838 [1/3] - httpd/httpd/trunk/docs/manual/rewrite
Date Thu, 17 Mar 2005 00:56:29 GMT
Author: rbowen
Date: Wed Mar 16 16:56:26 2005
New Revision: 157838

URL: http://svn.apache.org/viewcvs?view=rev&rev=157838
Log:
Move some the examples, technical details, and tutorial-style stuff into
its own place, somewhat like we did with mod_ssl and others. The main
module reference document should just be a module reference document,
and nothing more.

Added:
    httpd/httpd/trunk/docs/manual/rewrite/
    httpd/httpd/trunk/docs/manual/rewrite/index.html
    httpd/httpd/trunk/docs/manual/rewrite/index.html.en
    httpd/httpd/trunk/docs/manual/rewrite/index.xml
    httpd/httpd/trunk/docs/manual/rewrite/index.xml.meta
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.html
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.html.en
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.xml
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.xml.meta
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide_advanced.html
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide_advanced.html.en
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide_advanced.xml
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide_advanced.xml.meta
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_intro.html
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_intro.html.en
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_intro.xml
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_intro.xml.meta
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_tech.html
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_tech.html.en
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_tech.xml
    httpd/httpd/trunk/docs/manual/rewrite/rewrite_tech.xml.meta

Added: httpd/httpd/trunk/docs/manual/rewrite/index.html
URL: http://svn.apache.org/viewcvs/httpd/httpd/trunk/docs/manual/rewrite/index.html?view=auto&rev=157838
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/index.html (added)
+++ httpd/httpd/trunk/docs/manual/rewrite/index.html Wed Mar 16 16:56:26 2005
@@ -0,0 +1,3 @@
+URI: index.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1

Added: httpd/httpd/trunk/docs/manual/rewrite/index.html.en
URL: http://svn.apache.org/viewcvs/httpd/httpd/trunk/docs/manual/rewrite/index.html.en?view=auto&rev=157838
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/index.html.en (added)
+++ httpd/httpd/trunk/docs/manual/rewrite/index.html.en Wed Mar 16 16:56:26 2005
@@ -0,0 +1,97 @@
+<?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 - 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.0</p>
+<img alt="" src="../images/feather.gif" /></div>
+<div class="up"><a href="../"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
+<div id="path">
+<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="../">Version 2.0</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">&nbsp;en&nbsp;</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>
+
+      </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
+      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
+      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>) 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>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"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#documentation">Documentation</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#mod-rewrite">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="documentation" id="documentation">Documentation</a></h2>
+<ul>
+<li><a href="rewrite_intro.html">Introduction</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="../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="mod-rewrite" id="mod-rewrite">mod_rewrite</a></h2>
+<p>Extensive documentation on the directives 
+provided by this module is provided in the <a href="../mod/mod_rewrite.html">mod_rewrite reference documentation</a>.
+</p>
+</div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/rewrite/" title="English">&nbsp;en&nbsp;</a></p>
+</div><div id="footer">
+<p class="apache">Copyright 1995-2005 The Apache Software Foundation or its licensors, as applicable.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
+</body></html>
\ No newline at end of file

Added: httpd/httpd/trunk/docs/manual/rewrite/index.xml
URL: http://svn.apache.org/viewcvs/httpd/httpd/trunk/docs/manual/rewrite/index.xml?view=auto&rev=157838
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/index.xml (added)
+++ httpd/httpd/trunk/docs/manual/rewrite/index.xml Wed Mar 16 16:56:26 2005
@@ -0,0 +1,92 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision$ -->
+
+<!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors, as
+ applicable.
+
+ Licensed 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>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>
+
+      </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
+      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
+      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>) 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>But all this functionality and flexibility has its
+      drawback: complexity. So don't expect to understand this
+      entire module in just one day.</p>
+
+</summary>
+
+<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_tech.html">Technical details</a></li>
+<li><a href="rewrite_guide.html">Practical solutions to common
+problems</a></li>
+<li><a href="../glossary.html">Glossary</a></li>
+</ul>
+</section>
+
+</manualpage>
+
+

Added: httpd/httpd/trunk/docs/manual/rewrite/index.xml.meta
URL: http://svn.apache.org/viewcvs/httpd/httpd/trunk/docs/manual/rewrite/index.xml.meta?view=auto&rev=157838
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/index.xml.meta (added)
+++ httpd/httpd/trunk/docs/manual/rewrite/index.xml.meta Wed Mar 16 16:56:26 2005
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<metafile>
+  <basename>index</basename>
+  <path>/rewrite/</path>
+  <relpath>..</relpath>
+
+  <variants>
+    <variant>en</variant>
+  </variants>
+</metafile>

Added: httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.html
URL: http://svn.apache.org/viewcvs/httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.html?view=auto&rev=157838
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.html (added)
+++ httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.html Wed Mar 16 16:56:26 2005
@@ -0,0 +1,3 @@
+URI: rewrite_guide.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1

Added: httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.html.en
URL: http://svn.apache.org/viewcvs/httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.html.en?view=auto&rev=157838
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.html.en (added)
+++ httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.html.en Wed Mar 16 16:56:26 2005
@@ -0,0 +1,788 @@
+<?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.0</p>
+<img alt="" src="../images/feather.gif" /></div>
+<div class="up"><a href="./index.html"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
+<div id="path">
+<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="../">Version 2.0</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">&nbsp;en&nbsp;</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
+    commonony 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" /> Time-Dependent Rewriting</li>
+<li><img alt="" src="../images/down.gif" /> Backward Compatibility for YYYY to XXXX migration</li>
+<li><img alt="" src="../images/down.gif" /> <a href="#content">Content Handling</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#access">Access Restriction</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#other">Other</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_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   ^/([uge])/(<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}   !^fully\.qualified\.domain\.name [NC]
+RewriteCond %{HTTP_HOST}   !^$
+RewriteCond %{SERVER_PORT} !^80$
+RewriteRule ^/(.*)         http://fully.qualified.domain.name:%{SERVER_PORT}/$1 [L,R]
+</pre></div>
+
+<p>And for a site running on port 80</p>
+<div class="example"><pre>
+RewriteCond %{HTTP_HOST}   !^fully\.qualified\.domain\.name [NC]
+RewriteCond %{HTTP_HOST}   !^$
+RewriteRule ^/(.*)         http://fully.qualified.domain.name/$1 [L,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="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 custom/...
+#   ...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 pub/...
+#   ...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>Time-Dependent Rewriting</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>&lt;STRING</code>,
+          <code>&gt;STRING</code> and <code>=STRING</code> we can
+          do time-dependent redirects:</p>
+
+<div class="example"><pre>
+RewriteEngine on
+RewriteCond   %{TIME_HOUR}%{TIME_MIN} &gt;0700
+RewriteCond   %{TIME_HOUR}%{TIME_MIN} &lt;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>Backward Compatibility for YYYY to XXXX migration</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="content" id="content">Content Handling</a></h2>
+
+    
+
+    <h3>From Old to New (intern)</h3>
+
+      
+
+      <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>
+
+    
+
+    <h3>From Old to New (extern)</h3>
+
+      
+
+      <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>
+
+    
+
+    <h3>From Static to Dynamic</h3>
+
+      
+
+      <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
+          correct MIME-type so it gets really run as a CGI-script.
+          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>  [T=<strong>application/x-httpd-cgi</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="access" id="access">Access Restriction</a></h2>
+
+    
+
+    <h3>Blocking of Robots</h3>
+
+      
+
+      <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>
+
+    
+
+    <h3>Blocked Inline-Images</h3>
+
+      
+
+      <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>
+
+    
+
+    <h3>Proxy Deny</h3>
+
+      
+
+      <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="other" id="other">Other</a></h2>
+
+    
+
+    <h3>External Rewriting Engine</h3>
+
+      
+
+      <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 (&lt;&gt;) {
+    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">&nbsp;en&nbsp;</a></p>
+</div><div id="footer">
+<p class="apache">Copyright 1995-2005 The Apache Software Foundation or its licensors, as applicable.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
+</body></html>
\ No newline at end of file

Added: httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.xml
URL: http://svn.apache.org/viewcvs/httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.xml?view=auto&rev=157838
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.xml (added)
+++ httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.xml Wed Mar 16 16:56:26 2005
@@ -0,0 +1,781 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 123578 $ -->
+
+<!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors, as
+ applicable.
+
+ Licensed 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="./index.html" />
+
+  <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
+    commonony 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_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   ^/([uge])/(<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}   !^fully\.qualified\.domain\.name [NC]
+RewriteCond %{HTTP_HOST}   !^$
+RewriteCond %{SERVER_PORT} !^80$
+RewriteRule ^/(.*)         http://fully.qualified.domain.name:%{SERVER_PORT}/$1 [L,R]
+</pre></example>
+
+<p>And for a site running on port 80</p>
+<example><pre>
+RewriteCond %{HTTP_HOST}   !^fully\.qualified\.domain\.name [NC]
+RewriteCond %{HTTP_HOST}   !^$
+RewriteRule ^/(.*)         http://fully.qualified.domain.name/$1 [L,R]
+</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 custom/...
+#   ...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 pub/...
+#   ...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>
+
+      <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>&lt;STRING</code>,
+          <code>&gt;STRING</code> and <code>=STRING</code> we can
+          do time-dependent redirects:</p>
+
+<example><pre>
+RewriteEngine on
+RewriteCond   %{TIME_HOUR}%{TIME_MIN} &gt;0700
+RewriteCond   %{TIME_HOUR}%{TIME_MIN} &lt;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>
+
+      <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="content">
+
+    <title>Content Handling</title>
+
+    <section>
+
+      <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>
+
+      <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>
+
+      <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
+          correct MIME-type so it gets really run as a CGI-script.
+          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>  [T=<strong>application/x-httpd-cgi</strong>]
+</pre></example>
+        </dd>
+      </dl>
+
+    </section>
+</section>
+
+  <section id="access">
+
+    <title>Access Restriction</title>
+
+    <section>
+
+      <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>
+
+      <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>
+
+      <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>
+
+  <section id="other">
+
+    <title>Other</title>
+
+    <section>
+
+      <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 (&lt;&gt;) {
+    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>
+
+  </section>
+
+</manualpage>
+

Added: httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.xml.meta
URL: http://svn.apache.org/viewcvs/httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.xml.meta?view=auto&rev=157838
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.xml.meta (added)
+++ httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide.xml.meta Wed Mar 16 16:56:26 2005
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<metafile>
+  <basename>rewrite_guide</basename>
+  <path>/rewrite/</path>
+  <relpath>..</relpath>
+
+  <variants>
+    <variant>en</variant>
+  </variants>
+</metafile>

Added: httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide_advanced.html
URL: http://svn.apache.org/viewcvs/httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide_advanced.html?view=auto&rev=157838
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide_advanced.html (added)
+++ httpd/httpd/trunk/docs/manual/rewrite/rewrite_guide_advanced.html Wed Mar 16 16:56:26 2005
@@ -0,0 +1,3 @@
+URI: rewrite_guide_advanced.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1



Mime
View raw message