From d40815d5ec6480eab143979764f39eb8b321326e Mon Sep 17 00:00:00 2001 From: "Ralf S. Engelschall" Date: Wed, 4 Mar 1998 16:51:18 +0000 Subject: [PATCH] Phase 1 of mod_rewrite documentation enhancement: Adding of new information. Now especially the detailed information about how mod_rewrite internally works which is written down here for better understanding of the directive documentation. I've also painted two initial figures to illustrate this better which are added to htdocs/manual/images/. (Phase 2 will be error correction and markup code cleanup) git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@80404 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/images/mod_rewrite_fig1.fig | 60 ++++ docs/manual/images/mod_rewrite_fig1.gif | Bin 0 -> 3525 bytes docs/manual/images/mod_rewrite_fig2.fig | 50 ++++ docs/manual/images/mod_rewrite_fig2.gif | Bin 0 -> 2553 bytes docs/manual/mod/mod_rewrite.html | 371 +++++++++++++++++++----- 5 files changed, 401 insertions(+), 80 deletions(-) create mode 100644 docs/manual/images/mod_rewrite_fig1.fig create mode 100644 docs/manual/images/mod_rewrite_fig1.gif create mode 100644 docs/manual/images/mod_rewrite_fig2.fig create mode 100644 docs/manual/images/mod_rewrite_fig2.gif diff --git a/docs/manual/images/mod_rewrite_fig1.fig b/docs/manual/images/mod_rewrite_fig1.fig new file mode 100644 index 0000000000..7c80fea3f1 --- /dev/null +++ b/docs/manual/images/mod_rewrite_fig1.fig @@ -0,0 +1,60 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +0 32 #efefef +0 33 #cfcfef +0 34 #bebebe +2 1 0 4 4 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 6675 5250 6900 5250 6900 4650 4950 4650 4950 4050 5475 4050 +2 1 0 4 4 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 2.00 120.00 240.00 + 6900 4050 7650 4050 +2 1 0 4 4 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 9375 4050 9900 4050 9900 4650 7200 4650 7200 5250 7650 5250 +2 1 0 4 9 7 0 0 -1 0.000 0 0 -1 1 0 4 + 1 1 2.00 120.00 240.00 + 9300 5250 9900 5250 9900 6300 6975 6300 +2 1 2 4 0 7 0 0 -1 7.500 1 1 -1 0 0 2 + 3900 2100 3900 1500 +2 1 2 4 0 7 0 0 -1 7.500 1 1 -1 0 0 2 + 3900 7950 3900 7350 +2 1 1 4 9 7 0 0 -1 10.000 0 0 -1 1 0 4 + 1 1 2.00 120.00 240.00 + 5625 6300 2700 6300 2700 7050 3225 7050 +2 1 0 4 9 7 0 0 -1 0.000 0 0 -1 1 0 4 + 1 1 2.00 120.00 240.00 + 5550 3000 2700 3000 2700 5250 3225 5250 +2 1 1 4 9 7 0 0 -1 10.000 0 0 -1 1 0 4 + 1 1 2.00 120.00 240.00 + 9225 2325 9900 2325 9900 3000 6975 3000 +2 1 0 4 9 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 2.00 120.00 240.00 + 4800 5250 5550 5250 +2 4 0 2 9 7 0 0 -1 0.000 0 0 7 0 0 5 + 6900 3300 5700 3300 5700 2700 6900 2700 6900 3300 +2 4 0 2 9 7 0 0 -1 0.000 0 0 7 0 0 5 + 6900 6600 5700 6600 5700 6000 6900 6000 6900 6600 +4 0 0 0 0 0 20 0.0000 4 195 1455 3300 5400 RewriteRule\001 +4 0 0 0 0 1 20 0.0000 4 210 1440 7800 4200 CondPattern\001 +4 0 0 0 0 1 20 0.0000 4 270 1110 5625 4200 TestString\001 +4 0 0 0 0 0 20 0.0000 4 195 1905 3300 4200 RewriteCond \001 +4 0 0 0 0 1 20 0.0000 4 210 1320 7800 5400 Substitution\001 +4 0 0 0 0 1 20 0.0000 4 195 825 5700 5400 Pattern\001 +4 0 0 0 0 0 20 0.0000 4 195 1455 3300 7200 RewriteRule\001 +4 0 0 0 0 0 20 0.0000 4 195 1455 3300 2400 RewriteRule\001 +4 0 0 0 0 1 20 0.0000 4 195 825 5700 7200 Pattern\001 +4 0 0 0 0 1 20 0.0000 4 210 1320 7800 7200 Substitution\001 +4 0 0 0 0 1 20 0.0000 4 210 1320 7800 2400 Substitution\001 +4 0 0 0 0 1 20 0.0000 4 195 825 5700 2400 Pattern\001 +4 0 9 0 0 18 12 0.0000 4 135 645 6000 2925 current\001 +4 0 9 0 0 18 12 0.0000 4 135 375 6075 3150 URL\001 +4 0 9 0 0 18 12 0.0000 4 135 825 5925 6225 rewritten\001 +4 0 9 0 0 18 12 0.0000 4 135 375 6075 6450 URL\001 diff --git a/docs/manual/images/mod_rewrite_fig1.gif b/docs/manual/images/mod_rewrite_fig1.gif new file mode 100644 index 0000000000000000000000000000000000000000..664ac1e7bb7a186d2c6157878cdadd5bfb7d3466 GIT binary patch literal 3525 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 literal 0 HcmV?d00001 diff --git a/docs/manual/images/mod_rewrite_fig2.fig b/docs/manual/images/mod_rewrite_fig2.fig new file mode 100644 index 0000000000..facf410fc9 --- /dev/null +++ b/docs/manual/images/mod_rewrite_fig2.fig @@ -0,0 +1,50 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +0 32 #efefef +0 33 #cfcfef +0 34 #bebebe +2 1 2 4 0 7 0 0 -1 10.000 1 1 -1 0 0 2 + 4050 3750 4050 4425 +2 1 0 2 9 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 2.00 120.00 240.00 + 4950 4800 5550 4800 +2 1 0 2 9 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 2.00 120.00 240.00 + 4950 3600 5550 3600 +2 1 0 2 9 7 0 0 -1 0.000 0 0 -1 1 0 2 + 1 1 2.00 120.00 240.00 + 6600 5700 7725 5700 +2 1 0 2 9 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 6600 5550 6900 5550 6900 5100 4950 5100 4950 2850 5550 2850 +2 1 0 2 4 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 9525 4800 9750 4800 9750 5100 7200 5100 7200 5550 7725 5550 +2 1 0 2 4 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 9450 3000 9750 3000 9750 3225 5100 3225 5100 3450 5550 3450 +2 1 0 2 4 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 9450 3600 9750 3600 9750 3825 5100 3825 5100 4050 5550 4050 +2 1 0 2 4 7 0 0 -1 0.000 0 0 -1 1 0 6 + 1 1 2.00 120.00 240.00 + 9450 4200 9750 4200 9750 4425 5100 4425 5100 4650 5550 4650 +4 0 0 0 0 0 20 0.0000 4 195 1905 3300 4800 RewriteCond \001 +4 0 0 0 0 1 20 0.0000 4 210 1620 7800 4800 CondPatternN\001 +4 0 0 0 0 0 20 0.0000 4 195 1905 3300 3600 RewriteCond \001 +4 0 0 0 0 1 20 0.0000 4 210 1575 7800 3600 CondPattern2\001 +4 0 0 0 0 1 20 0.0000 4 270 1290 5625 4800 TestStringN\001 +4 0 0 0 0 1 20 0.0000 4 270 1245 5625 3600 TestString2\001 +4 0 0 0 0 0 20 0.0000 4 195 1905 3300 3000 RewriteCond \001 +4 0 0 0 0 1 20 0.0000 4 270 1245 5625 3000 TestString1\001 +4 0 0 0 0 1 20 0.0000 4 210 1575 7800 3000 CondPattern1\001 +4 0 0 0 0 1 20 0.0000 4 210 1320 7800 5700 Substitution\001 +4 0 0 0 0 1 20 0.0000 4 195 825 5700 5700 Pattern\001 +4 0 0 0 0 0 20 0.0000 4 195 1455 3300 5700 RewriteRule\001 diff --git a/docs/manual/images/mod_rewrite_fig2.gif b/docs/manual/images/mod_rewrite_fig2.gif new file mode 100644 index 0000000000000000000000000000000000000000..3ea8cb65a3f9f1682c6b52d3911f52d2434ad38f GIT binary patch literal 2553 zcmV*@J5W=b#yB~Kp0=~-bve892N4)}p(pW%2p5sZht~LD zI1%}hx8|otxH2g-xLK0vxppC@5V~NentIoI(rJ0{2OE+}BP-$wx*=Bz983yn zON(iU%aN>EEQsprz_yI0Q)?}KoO*nQ-CZ_4KxX`yc3=u2d>*X_(0`guqzqd@*%#-LfeXh5BVQWpLp z)QG8|NtFn{$$Q4mA4HAe4t}G#aHU6(6t}s=hq0PVmJMrKq`A|k!e|9O8l4z&!W#`S zjZ$>#(5cRsJn6|i1(K`QjsTk`MM>77$!02Ard6pHsnu+78$i8lc7VuF^ky0)tFtHF zr(QWty35d@Uzmf7Y8_lL2S2v}^FhUV^=(jScxmn>5x6qvpoM!Pb&QqLVZdksM=H$I z>f6||`_!fUG4I*j11X7%v6>pY2xh3(3xa*;o zNYwSdUv1ZB&wdX*)_krZ4vewXW?IWbBeN8I)p6nPzS&B?4Ba$!41htm$T)Y{DsLok!AXXP!Iasb`-s^66)wB?2mFp%M~m zXrkQ3=fOx@uY&%$*{vTrQ0I{>pr{8vB)Ijjp5X8oW+QCNZyu6c=x)f=Sie!59OmW78?Uq0#Q z-A_M>*2j0|B3IR1{j3WUtyZmwDmAPb*OzWZ(KlCd!!olPXD?x<)MZ`WCSOCy2xXtD zBJXyVst}vinMV{8xGT+dtvA`ugw^Np$GNUjU414?N3v`l^XJ|U-Mw}&ZPjtd6m(DJ z6=fj;N4r>Zw<*{1t;9aJ(R|1-mS1mQ3*BsPl^rbC)KrgcT-_5(HI>#v|5g>Q3aoBpX0Y3fE=(`y56f!k?an7cM1Y2Z z>89<%9O0m%5>UCP<%ld{q4w}rZ#fjfi|+vUI%bW2f9l`Je*0g%Phpa(w)!Vrq^ zK;-L{1y9HXM4@nnK~NzJU&sR&!f=MpVu1{4I70`L;D$JSp$#5&cs{ zYT@jNOnhJx6M&^AO3?#^;?n*Uuh<3#lnIMmM8^c;)kQ!3a6w;0P#6_8#t_^LgJ*0~ z8bMIOHp($7bF3p3?TE(>#4(Rt+#?@BK)p8k@sBNFBX(pkNJ5^-eBJ6mA{CheLyiju zkA&n2BzXe>G;%|hOadk^RLM@dsDz>{!Y2<^N+X=|L7_|~AW7-UAgr=&FKA^fYs5%I z`f7x{?4>V%3Cv(F(FvN=r3r6Y#~>n;iOO825u52uAwn~nIGiRmXK2l9zA&5GEP^J# zSxjy@;+s@?7XnT-%uMkmW9qbo!NR!*cxJ^gHB45ja8-zDopYBYWED8c87Y7YLT~j< z!9TkN&v44KJU)w6L;elAvYZ*|nCAo|*E}W(wrLbBv>95q?)j~FcCxUUeXSS_qn!ztLk!=+AD_Zz6^so0i)aBZQiC`j+k z*P9!?-z)_r-R~*Ey)V3Rf27Mu^G49eU|?}Kw+G83*MP`hFtU<|l;kJNfXQBPvXr$L z_+~zF2`O9&Z^NR0`=RE7#d1Vx) zpa1;+r88#{$%0-X#R_fcFCrR+hhDS=8|`QXLORm?n>3~6XX#6$FVmXV9;Z87n?$UQ1dKj$WxKWt%&lC&*2KeJ zg|Jc^3%8wSJbJ~>Es5hsvVku&bMOtThffzVrY3bjZp9qQL0cRG3m7&S2lxLF`)k|Z zf?Q-y{q1!w@@ujE{JG!dHe$z|&Vcqbv=aBY>W)J$AvZ9!qFH%?Ma*N^PF&p0-WiVv zzMQNZfxTa!4%O>=-_E_8*b=)>dpCpizhqA8omJk;HIvg6=s4YH_3mYv&UCJ#46a;f zD6N=H-t{KN>tGW*NzbkI=0cs4Ge);y`zlrYMtkMWtfc2gZs#07qC6*Y8&p!K)?pjTI?meG(PwMLdKh&2SzNe>a{NyWt`OI&=^Pdm> P=u3b4)UW=R3jhE+CPVN4 literal 0 HcmV?d00001 diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html index 2cb8b4ca69..5b239d8271 100644 --- a/docs/manual/mod/mod_rewrite.html +++ b/docs/manual/mod/mod_rewrite.html @@ -15,54 +15,86 @@ VLINK="#000080" ALINK="#FF0000" > +
-

Module mod_rewrite

+
+

Module mod_rewrite
URL Rewriting Engine

This module is contained in the mod_rewrite.c file, with Apache -1.2 and later. It provides a rule-based rewriting engine to rewrite requested -URLs on the fly. mod_rewrite is not compiled into the server by -default. To use mod_rewrite you have to enable the following line -in the server build Configuration file: +1.2 and later. It provides a rule-based rewriting engine to rewrite requested +URLs on the fly. It is not compiled into the server by default. To use +mod_rewrite you have to enable the following line in the server +build Configuration file: 
     AddModule  modules/standard/mod_rewrite.o
+
+ +

Summary

-This module uses a rule-based rewriting engine (based on a -regular-expression parser) to rewrite requested URLs on the fly. +
+
+
+,,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.'' +
+-- Brian Behlendorf
+Apache Group +
+
+
+
+ +Welcome to mod_rewrite, the Swiss Army Knife of URL manipulation!

-It supports an unlimited number of additional rule conditions (which can -operate on a lot of variables, including HTTP headers) for granular -matching and external database lookups (either via plain text -tables, DBM hash files or external processes) for advanced URL -substitution. +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, timestamps and even external database +lookups in various formats can be used to achieve a really granular URL +matching.

-It operates on the full URLs (including the PATH_INFO part) both in per-server -context (httpd.conf) and per-dir context (.htaccess) and even can generate -QUERY_STRING parts on result. The rewritten result can lead to internal -sub-processing, external request redirection or to internal proxy throughput. +This module operates on the full URLs (including the path-info part) both in +per-server context (httpd.conf) and per-directory context +(.htaccess) and even can 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.

-This module was originally written in April 1996 and -gifted exclusively to the The Apache Group in July 1997 by +But all this functionality and flexibility has its drawback: complexity. So +don't expect to understand this module in it's whole in just one day. +

+This module was invented and originally written in April 1996
+and gifted exclusively to the The Apache Group in July 1997 by

- Ralf S. Engelschall
+ Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
- -
- +
-

-

Directives

+

Table Of Contents

+

+Internal Processing +

+

+Configuration Directives

+Miscellaneous + - -
- +
+
+

Internal Processing

+
+ +
+ +

+The internal processing of this module is very complex but needs to be +explained once even to the average user to avoid common mistakes and to let +you exploit its full funtionality. + +

API Phases

+ +

+First you have to understand that when Apache processes a HTTP request it does +this in phases. A hook for each of these phases is provided by the Apache API. +Mod_rewrite uses two of these hooks: the URL-to-filename translation hook +which is used after the HTTP request was read and before any authorization +starts and the Fixup hook which is triggered after the authorization phases +and after the per-directory config files (.htaccess) where read, +but before the content handler is activated. + +

+So, after a request comes in and Apache has determined the corresponding +server (or virtual server) the rewriting engine start processing of all +mod_rewrite directives from the per-server configuration in the +URL-to-filename phase. A few steps later when the final data directories are +found, the per-directory configuration directives of mod_rewrite are triggered +in the Fixup phase. In both situations mod_rewrite either rewrites URLs to new +URLs or to filenames, although there is no obvious distinction between them. +This is a usage of the API which was not intended this way when the API +was designed, but as of Apache 1.x this is the only way mod_rewrite can +operate. To make this point more clear remember the following two points: + +

    +
  1. The API currently provides only a URL-to-filename hook. Although + mod_rewrite rewrites URLs to URLs, URLs to filenames and even + filenames to filenames. In Apache 2.0 the two missing hooks + will be added to make the processing more clear. But this + point has no drawbacks for the user, it is just a fact which + should be remembered: Apache does more in the URL-to-filename hook + then the API intends for it. +

    +

  2. Unbelievably mod_rewrite provides URL manipulations in per-directory + context, i.e. within .htaccess files, although these are + reached a very long time after the URLs were translated to filenames (this + has to be this way, because .htaccess files stay in the + filesystem, so processing has already been reached this stage of + processing). In other words: According to the API phases at this time it + is too late for any URL manipulations. To overcome this chicken and egg + problem mod_rewrite uses a trick: When you manipulate a URL/filename in + per-directory context mod_rewrite first rewrites the filename back to its + corresponding URL (which it usually impossible, but see the + RewriteBase directive below for the trick to achieve this) + and then initiates a new internal sub-request with the new URL. This leads + to a new processing of the API phases from the beginning. +

    + Again mod_rewrite tries hard to make this complicated step totally + transparent to the user, but you should remember here: While URL + manipulations in per-server context are really fast and efficient, + per-directory rewrites are slow and inefficient due to this chicken and + egg problem. But on the other hand this is the only way mod_rewrite can + provide (locally restricted) URL manipulatiuons to the avarage user. +

+ +

+Don't forget these two points! + +

Ruleset Processing

+ +Now when mod_rewrite is triggered in these two API phases, it reads the +configured rulesets from its configuration structure (which itself was either +created on startup for per-server context or while the directory walk of the +Apache kernel for per-directory context). Then the URL rewriting engine is +started with the contained ruleset (one or more rules together with their +conditions). The operation of the URL rewriting engine itself is exactly the +same for both configuration contexts. Just the final result processing is +different. + +

+The order of rules in the ruleset is important because the rewriting engine +processes them in a special order. And this order is not very obvious. The +rule is this: The rewriting engine loops through the ruleset rule by rule +(RewriteRule directives!) and when a particular rule matched it +optionally loops through existing corresponding conditions +(RewriteCond directives). Because of historical reasons the +conditions are given first, the control flow is a little bit winded. See +Figure 1 for more details. + +

+

+ + + + + + + +
[Needs graphics capability to display]
+Figure 1: The control flow through the rewriting ruleset +
+
+ +

+As you can see, first the URL is matched against the Pattern of each +rule. When it fails mod_rewrite immediately stops processing this rule and +continues with the next rule. If the Pattern matched, mod_rewrite +looks for corresponding rule conditions. If none are present, it just +substitutes the URL with a new value which is constructed from the string +Substitution and goes on with its rule-looping. But if conditions But +if conditions exists, it starts an inner loop for processing them in order +they are listed. For conditions the logic is different: We don't match a +pattern against the current URL. Instead we first create a string +TestString by expanding variables, back-references, map lookups, etc. +and then we try to match TestPattern against it. If the pattern +doesn't match, the complete set of conditions and the corresponding rule fails. +If the pattern matches, then the next condition is processed until no more +condition is available. If all conditions matched processing is continued with +the substitution of the URL with Substitution. + +

Regex Back-Reference Availability

+ +One important thing here has to be rememberd: Whenever you +use parenthesis in Pattern or in one of the TestPattern +back-reference are internally created which can be used with the +strings $N and %N (see below). And these +are available for creating the strings Substitution and +TestCond. Figure 2 shows at which locations the back-references are +transfered to for expansion. + +

+

+ + + + + + + +
[Needs graphics capability to display]
+Figure 2: The back-reference flow through a rule +
+
+ +

+We know, this was a crash course of mod_rewrite's internal processing. But +you will benefit from this knowledge when reading the following documentation +of the available directives. + +

+

Configuration Directives

+
+

RewriteEngine

RewriteRule directives!

Note that, by default, rewrite configurations are not inherited. This means that you need to have a RewriteEngine on -directive for each virtual host you wish to use it in, unless RewriteOptions inherit is enabled. +directive for each virtual host you wish to use it in.

@@ -172,9 +361,9 @@ with a slash ('/') then it is assumed to be relative to the config.

- +
-To disable the logging of rewriting actions it is not recommended +Notice: To disable the logging of rewriting actions it is not recommended to set Filename to /dev/null, because although the rewriting engine does not create output to a logfile it still creates the logfile @@ -186,9 +375,9 @@ To disable logging either remove or comment out the

- +
-SECURITY: See the Security: See the Apache Security Tips document for details on why your security could be compromised if the directory where logfiles are stored is writable by anyone other than the user @@ -232,7 +421,7 @@ To disable the logging of rewriting actions simply set Level to 0. This disables all rewrite action logs.

- +
Notice: Using a high value for Level will slow down your Apache server dramatically! Use the rewriting logfile only for debugging or at least @@ -325,16 +514,16 @@ can be used:
  • Standard Plain Text
    MapType: txt, MapSource: Unix filesystem path to valid regular file

    - This is the standard rewriting map feature where the MapSource is - a plain ASCII file containing either blank lines, comment lines (starting - with a '#' character) or pairs like the following - one per line. + This is the standard rewriting map feature where the MapSource is + a plain ASCII file containing either blank lines, comment lines (starting + with a '#' character) or pairs like the following - one per line.

    MatchingKey SubstValue

    - Example: + Example: 

    @@ -358,14 +547,14 @@ RewriteMap real-to-host txt:/path/to/file/map.txt
 
  • Randomized Plain Text
    
     MapType: rnd, MapSource: Unix filesystem path to valid regular file
     
    
-	This is identical to the Standard Plain Text variant above but with a special
-	post-processing feature: After looking up a value it is parsed according
+    This is identical to the Standard Plain Text variant above but with a special
+    post-processing feature: After looking up a value it is parsed according
     to contained ``|'' characters which have the meaning of ``or''.  Or
     in other words: they indicate a set of alternatives from which the actual
     returned value is choosen randomly. Although this sounds crazy and useless, it
     was actually designed for load balancing in a reverse proxy situation where
     the looked up values are server names.
-	Example:
+    Example:
 
    
 
    
 
    @@ -389,8 +578,8 @@ RewriteMap servers rnd:/path/to/file/map.txt
 
  • Hash File
    
     MapType: dbm, MapSource: Unix filesystem path to valid regular file
     
    
-	Here the source is a binary NDBM format file containing the same contents
-	as a Plain Text format file, but in a special representation
+    Here the source is a binary NDBM format file containing the same contents
+    as a Plain Text format file, but in a special representation
     which is optimized for really fast lookups. You can create such a file with
     any NDBM tool or with the following Perl script:
     
    
@@ -411,7 +600,7 @@ while (<TXT>) {
 dbmclose(%DB);
 close(TXT)
    • 
     
    
-	
    
+    
    
     
    
     
    $ txt2dbm map.txt map.db 
    
     
    
@@ -479,9 +668,9 @@ context it is of course possible to use this map in per-directo
 context.
 
 
    
-
+
    
 
    
-For plain text and DBM format files the looked-up keys are cached in-core
+Notice: For plain text and DBM format files the looked-up keys are cached in-core
 until the mtime of the mapfile changes or the server does a
 restart. This way you can have map-functions in rules which are used
 for every request. This is no problem, because the external lookup
@@ -526,9 +715,9 @@ will be usually be wrong! There you have to use the RewriteBase
-
+
    
 
    
-So, if your webserver's URLs are not directly
+Notice: If your webserver's URLs are not directly
 related to physical file paths, you have to use RewriteBase in every
 .htaccess files where you want to use RewriteRule
 directives.
@@ -566,10 +755,10 @@ In the above example, a request to /xyz/oldstuff.html gets correctly
 rewritten to the physical file /abc/def/newstuff.html.
 
 
    
-
+
    
 
    
 
-For the Apache hackers:
    
+Notice - For the Apache hackers:
    
 The following list gives detailed information about the internal
 processing steps:
 
@@ -626,7 +815,7 @@ The RewriteCond directive defines a rule condition. Precede a
 directives.
 
 The following rewriting rule is only used if its pattern matches the current
-state of the URI AND if these additional conditions apply, too.
+state of the URI and if these additional conditions apply, too.
 
 
    
 TestString is a string which can contains the following
@@ -741,11 +930,11 @@ IS_SUBREQ
    
 
    
 
 
    
-
+
    
 
    
-These variables all correspond to the similar named HTTP MIME-headers, C
-variables of the Apache server or struct tm fields of the Unix
-system.
+Notice: These variables all correspond to the similar named
+HTTP MIME-headers, C variables of the Apache server or struct tm
+fields of the Unix system.
 
    
 
    
 
@@ -861,8 +1050,13 @@ subrequest to determine the check, so use it with care because it decreases
 your servers performance!
 
 
    
-Notice: All of these tests can also be prefixed by a not ('!') character
+
+
+
    
+Notice:
+All of these tests can also be prefixed by a not ('!') character
 to negate their meaning.
+
    
 
 
 
    
@@ -986,9 +1180,9 @@ for special cases where it is better to match the negative pattern or as a
 last default rule.
 
 
    
-
+
    
 
    
-Notice! When using the NOT character to negate a pattern you cannot
+Notice: When using the NOT character to negate a pattern you cannot
 have grouped wildcard parts in the pattern. This is impossible because when
 the pattern does NOT match, there are no contents for the groups. In
 consequence, if negated patterns are used, you cannot use $N in the
@@ -1038,7 +1232,7 @@ QUERY_STRING.  When you want to erase an existing query string, end the
 substitution string with just the question mark.
 
 
    
-
+
    
+
    
 
    
 Notice: There is a special feature. When you prefix a substitution
 field with http://thishost[:thisport] then
@@ -1047,7 +1241,11 @@ implicit external redirect URLs is a useful and important feature when
 used in combination with a mapping-function which generates the hostname
 part.  Have a look at the first example in the example section below to
 understand this.
+
    
 
    
+
+
    
 Remember: An unconditional external redirect to your own server will
 not work with the prefix http://thishost because of this feature.
 To achieve such a self-redirect, you have to use the R-flag (see
@@ -1066,7 +1264,7 @@ as the third argument to the RewriteRule directive. Flags is a
 comma-separated list of the following flags:
 
 
      
-
    • 'redirect|R[=code]' (force redirect)
      
+
    • 'redirect|R [=code]' (force redirect)
      
     Prefix Substitution
     with http://thishost[:thisport]/ (which makes the new URL a URI) to
     force a external redirection. If no code is given a HTTP response
@@ -1193,10 +1391,10 @@ comma-separated list of the following flags:
     typical example is the use of mod_alias and
     mod_rewrite..
 
      
-
+
      
 
      
 
-    For the Apache hackers:
      
+    Notice - For the Apache hackers:
      
     If the current Apache API had a
     filename-to-filename hook additionally to the URI-to-filename hook then
     we wouldn't need this flag!  But without  such a hook this flag is the
@@ -1214,21 +1412,21 @@ comma-separated list of the following flags:
     (This is not the same as the 'chain|C' flag!)
 
      
 
    • 'env|E=VAR:VAL' (set environment variable)
      
-	This forces an environment variable named VAR to be set to the
-	value VAL, where VAL can contain regexp backreferences
-	$N and %N which will be expanded. You can use this flag
-	more than once to set more than one variable. The variables can be later
-	dereferenced at a lot of situations, but the usual location will be from
-	within XSSI (via <!--#echo var="VAR"-->) or CGI (e.g.
-	$ENV{'VAR'}).  But additionally you can also dereference it in a
-	following RewriteCond pattern via %{ENV:VAR}. Use this to strip
-	but remember information from URLs.
+    This forces an environment variable named VAR to be set to the
+    value VAL, where VAL can contain regexp backreferences
+    $N and %N which will be expanded. You can use this flag
+    more than once to set more than one variable. The variables can be later
+    dereferenced at a lot of situations, but the usual location will be from
+    within XSSI (via <!--#echo var="VAR"-->) or CGI (e.g.
+    $ENV{'VAR'}).  But additionally you can also dereference it in a
+    following RewriteCond pattern via %{ENV:VAR}. Use this to strip
+    but remember information from URLs.
 
 
 
      
-
+
      
 
      
-Remember: Never forget that Pattern gets applied to a complete URL
+Notice: Never forget that Pattern gets applied to a complete URL
 in per-server configuration files. But in per-directory configuration
 files, the per-directory prefix (which always is the same for a specific
 directory!) gets automatically removed for the pattern matching and
@@ -1243,9 +1441,9 @@ external redirect or proxy throughput (if flag P is used!) is f
 
      
 
 
      
-
+
      
 
      
-Notice!  To enable the rewriting engine for per-directory configuration files
+Notice: To enable the rewriting engine for per-directory configuration files
 you need to set ``RewriteEngine On'' in these files and
 ``Option FollowSymLinks'' enabled. If your administrator has
 disabled override of FollowSymLinks for a user's directory, then
@@ -1381,15 +1579,14 @@ RewriteRule  ^/([^/]+)/~([^/]+)/(.*)$   /u/${real-to-user:$2|nobody}/$3.$1
 
 
 
-
-
-
      
-
+
      
 
 
      
-
      Additional Features
      
+
      Miscellaneous
      
 
      
 
+
      
+
 
      Environment Variables
      
 
 This module keeps track of two additional (non-standard) CGI/SSI environment
@@ -1416,8 +1613,22 @@ SCRIPT_URI=http://en2.en.sdm.de/u/rse/
 
 
 
+
      
+
+
      Practical Solutions
      
+
+There is a comprehensive collection of practical solutions for URL-based
+problems available by the author of mod_rewrite.  Here you will find real-life
+rulesets and additional information.
+
+
      
+Apache URL Rewriting Guide
      
+http://www.engelschall.com/pw/apache/rewriteguide/
+
      
 
 
+
      
 
 
 
-- 
2.50.1