granicus.if.org Git - apache/blob - docs/manual/mod/mod_rewrite.html.en

   1 <html xmlns="http://www.w3.org/TR/xhtml1/strict"><head><!--
   2           XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   3                 This file is generated from xml source: DO NOT EDIT
   4           XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5         --><title>mod_rewrite- Apache HTTP Server</title><link href="../style/manual.css" type="text/css" rel="stylesheet"/></head><body><blockquote><div align="center"><img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]"/><h3>Apache HTTP Server Version 2.0</h3></div><h1 align="center">Apache Module mod_rewrite</h1><table cellspacing="1" cellpadding="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td valign="top"><span class="help">Description:</span></td><td>Provides a rule-based rewriting engine to rewrite requested
   6 URLs on the fly</td></tr><tr><td><a href="module-dict.html#Status" class="help">Status:</a></td><td>Extension</td></tr><tr><td><a href="module-dict.html#ModuleIdentifier" class="help">Module&nbsp;Identifier:</a></td><td>rewrite_module</td></tr><tr><td align="left" valign="top"><a href="module-dict.html#Compatibility" class="help">Compatibility:</a></td><td><compatibility>Available in Apache 1.3 and later</compatibility></td></tr></table></td></tr></table><h2>Summary</h2>
   7       <blockquote>
   8             <em>``The great thing about mod_rewrite is it gives you
   9             all the configurability and flexibility of Sendmail.
  10             The downside to mod_rewrite is that it gives you all
  11             the configurability and flexibility of Sendmail.''</em><br>
  12
  13             &nbsp;&nbsp;&nbsp;&nbsp;  -- Brian Behlendorf<br>
  14             &nbsp;&nbsp;&nbsp;&nbsp;   Apache Group
  15
  16       </blockquote>
  17
  18       <blockquote>
  19             <em>`` Despite the tons of examples and docs,
  20             mod_rewrite is voodoo. Damned cool voodoo, but still
  21             voodoo. ''</em> <br>
  22
  23               &nbsp;&nbsp;&nbsp;&nbsp;-- Brian Moore<br>
  24               &nbsp;&nbsp;&nbsp;&nbsp; bem@news.cmc.net
  25
  26           </blockquote>
  27
  28
  29       <p>Welcome to mod_rewrite, the Swiss Army Knife of URL
  30       manipulation!</p>
  31
  32       <p>This module uses a rule-based rewriting engine (based on a
  33       regular-expression parser) to rewrite requested URLs on the
  34       fly. It supports an unlimited number of rules and an
  35       unlimited number of attached rule conditions for each rule to
  36       provide a really flexible and powerful URL manipulation
  37       mechanism. The URL manipulations can depend on various tests,
  38       for instance server variables, environment variables, HTTP
  39       headers, time stamps and even external database lookups in
  40       various formats can be used to achieve a really granular URL
  41       matching.</p>
  42
  43       <p>This module operates on the full URLs (including the
  44       path-info part) both in per-server context
  45       (<code>httpd.conf</code>) and per-directory context
  46       (<code>.htaccess</code>) and can even generate query-string
  47       parts on result. The rewritten result can lead to internal
  48       sub-processing, external request redirection or even to an
  49       internal proxy throughput.</p>
  50
  51       <p>But all this functionality and flexibility has its
  52       drawback: complexity. So don't expect to understand this
  53       entire module in just one day.</p>
  54
  55       <p>This module was invented and originally written in April
  56       1996 and gifted exclusively to the The Apache Group in July 1997
  57       by</p>
  58
  59       <blockquote>
  60         <a href="http://www.engelschall.com/"><code>Ralf S.
  61         Engelschall</code></a><br>
  62          <a href="mailto:rse@engelschall.com"><code>rse@engelschall.com</code></a><br>
  63          <a href="http://www.engelschall.com/"><code>www.engelschall.com</code></a>
  64       </blockquote>
  65 <h2>Directives</h2><ul><li><a href="#rewritebase">RewriteBase</a></li><li><a href="#rewritecond">RewriteCond</a></li><li><a href="#rewriteengine">RewriteEngine</a></li><li><a href="#rewritelock">RewriteLock</a></li><li><a href="#rewritelog">RewriteLog</a></li><li><a href="#rewriteloglevel">RewriteLogLevel</a></li><li><a href="#rewritemap">RewriteMap</a></li><li><a href="#rewriteoptions">RewriteOptions</a></li><li><a href="#rewriterule">RewriteRule</a></li></ul><h2><a name="Internal">Interal Processing</a></h2>
  66
  67       <p>The internal processing of this module is very complex but
  68       needs to be explained once even to the average user to avoid
  69       common mistakes and to let you exploit its full
  70       functionality.</p>
  71
  72 <h3><a name="InternalAPI">API Phases</a></h3>
  73
  74       <p>First you have to understand that when Apache processes a
  75       HTTP request it does this in phases. A hook for each of these
  76       phases is provided by the Apache API. Mod_rewrite uses two of
  77       these hooks: the URL-to-filename translation hook which is
  78       used after the HTTP request has been read but before any
  79       authorization starts and the Fixup hook which is triggered
  80       after the authorization phases and after the per-directory
  81       config files (<code>.htaccess</code>) have been read, but
  82       before the content handler is activated.</p>
  83
  84       <p>So, after a request comes in and Apache has determined the
  85       corresponding server (or virtual server) the rewriting engine
  86       starts processing of all mod_rewrite directives from the
  87       per-server configuration in the URL-to-filename phase. A few
  88       steps later when the final data directories are found, the
  89       per-directory configuration directives of mod_rewrite are
  90       triggered in the Fixup phase. In both situations mod_rewrite
  91       rewrites URLs either to new URLs or to filenames, although
  92       there is no obvious distinction between them. This is a usage
  93       of the API which was not intended to be this way when the API
  94       was designed, but as of Apache 1.x this is the only way
  95       mod_rewrite can operate. To make this point more clear
  96       remember the following two points:</p>
  97
  98       <ol>
  99         <li>Although mod_rewrite rewrites URLs to URLs, URLs to
 100         filenames and even filenames to filenames, the API
 101         currently provides only a URL-to-filename hook. In Apache
 102         2.0 the two missing hooks will be added to make the
 103         processing more clear. But this point has no drawbacks for
 104         the user, it is just a fact which should be remembered:
 105         Apache does more in the URL-to-filename hook than the API
 106         intends for it.</li>
 107
 108         <li>
 109           Unbelievably mod_rewrite provides URL manipulations in
 110           per-directory context, <em>i.e.</em>, within
 111           <code>.htaccess</code> files, although these are reached
 112           a very long time after the URLs have been translated to
 113           filenames. It has to be this way because
 114           <code>.htaccess</code> files live in the filesystem, so
 115           processing has already reached this stage. In other
 116           words: According to the API phases at this time it is too
 117           late for any URL manipulations. To overcome this chicken
 118           and egg problem mod_rewrite uses a trick: When you
 119           manipulate a URL/filename in per-directory context
 120           mod_rewrite first rewrites the filename back to its
 121           corresponding URL (which is usually impossible, but see
 122           the <code>RewriteBase</code> directive below for the
 123           trick to achieve this) and then initiates a new internal
 124           sub-request with the new URL. This restarts processing of
 125           the API phases.
 126
 127           <p>Again mod_rewrite tries hard to make this complicated
 128           step totally transparent to the user, but you should
 129           remember here: While URL manipulations in per-server
 130           context are really fast and efficient, per-directory
 131           rewrites are slow and inefficient due to this chicken and
 132           egg problem. But on the other hand this is the only way
 133           mod_rewrite can provide (locally restricted) URL
 134           manipulations to the average user.</p>
 135         </li>
 136       </ol>
 137
 138       <p>Don't forget these two points!</p>
 139
 140
 141 <h3><a name="InternalRuleset">Ruleset Processing</a></h3>
 142
 143       <p>Now when mod_rewrite is triggered in these two API phases, it
 144       reads the configured rulesets from its configuration
 145       structure (which itself was either created on startup for
 146       per-server context or during the directory walk of the Apache
 147       kernel for per-directory context). Then the URL rewriting
 148       engine is started with the contained ruleset (one or more
 149       rules together with their conditions). The operation of the
 150       URL rewriting engine itself is exactly the same for both
 151       configuration contexts. Only the final result processing is
 152       different. </p>
 153
 154       <p>The order of rules in the ruleset is important because the
 155       rewriting engine processes them in a special (and not very
 156       obvious) order. The rule is this: The rewriting engine loops
 157       through the ruleset rule by rule (<a href="#rewriterule" class="directive"><code class="directive">RewriteRule</code></a> directives) and
 158       when a particular rule matches it optionally loops through
 159       existing corresponding conditions (<code>RewriteCond</code>
 160       directives). For historical reasons the conditions are given
 161       first, and so the control flow is a little bit long-winded. See
 162       Figure 1 for more details.</p>
 163 <h3/>
 164       <img src="../images/mod_rewrite_fig1.gif" border="1" width="428" height="385" alt="[Needs graphics capability to display]">
 165       <p><strong>Figure 1:</strong>The control flow through the rewriting ruleset</p>
 166
 167       <p>As you can see, first the URL is matched against the
 168       <em>Pattern</em> of each rule. When it fails mod_rewrite
 169       immediately stops processing this rule and continues with the
 170       next rule. If the <em>Pattern</em> matches, mod_rewrite looks
 171       for corresponding rule conditions. If none are present, it
 172       just substitutes the URL with a new value which is
 173       constructed from the string <em>Substitution</em> and goes on
 174       with its rule-looping. But if conditions exist, it starts an
 175       inner loop for processing them in the order that they are
 176       listed. For conditions the logic is different: we don't match
 177       a pattern against the current URL. Instead we first create a
 178       string <em>TestString</em> by expanding variables,
 179       back-references, map lookups, <em>etc.</em> and then we try
 180       to match <em>CondPattern</em> against it. If the pattern
 181       doesn't match, the complete set of conditions and the
 182       corresponding rule fails. If the pattern matches, then the
 183       next condition is processed until no more conditions are
 184       available. If all conditions match, processing is continued
 185       with the substitution of the URL with
 186       <em>Substitution</em>.</p>
 187
 188
 189
 190 <h3><a name="quoting">Quoting Special Characters</a></h3>
 191
 192       <p>As of Apache 1.3.20, special characters in
 193       <em>TestString</em> and <em>Substitution</em> strings can be
 194       escaped (that is, treated as normal characters without their
 195       usual special meaning) by prefixing them with a slosh ('\')
 196       character. In other words, you can include an actual
 197       dollar-sign character in a <em>Substitution</em> string by
 198       using '<code>\$</code>'; this keeps mod_rewrite from trying
 199       to treat it as a backreference.</p>
 200
 201
 202 <h3><a name="InternalBackRefs">Regex Back-Reference Availability</a></h3>
 203
 204       <p>One important thing here has to be remembered: Whenever you
 205       use parentheses in <em>Pattern</em> or in one of the
 206       <em>CondPattern</em>, back-references are internally created
 207       which can be used with the strings <code>$N</code> and
 208       <code>%N</code> (see below). These are available for creating
 209       the strings <em>Substitution</em> and <em>TestString</em>.
 210       Figure 2 shows to which locations the back-references are
 211       transfered for expansion.</p>
 212
 213 <h3/>
 214       <img src="../images/mod_rewrite_fig2.gif" border="1" width="381" height="179" alt="[Needs graphics capability to display]">
 215       <p><strong>Figure 2:</strong> The back-reference flow through a rule.</p>
 216
 217       <p>We know this was a crash course on mod_rewrite's internal
 218       processing. But you will benefit from this knowledge when
 219       reading the following documentation of the available
 220       directives.</p>
 221
 222
 223 <h2><a name="EnvVar">Environment Variables</a></h2>
 224
 225       <p>This module keeps track of two additional (non-standard)
 226       CGI/SSI environment variables named <code>SCRIPT_URL</code>
 227       and <code>SCRIPT_URI</code>. These contain the
 228       <em>logical</em> Web-view to the current resource, while the
 229       standard CGI/SSI variables <code>SCRIPT_NAME</code> and
 230       <code>SCRIPT_FILENAME</code> contain the <em>physical</em>
 231       System-view. </p>
 232
 233       <p>Notice: These variables hold the URI/URL <em>as they were
 234       initially requested</em>, <em>i.e.</em>, <em>before</em> any
 235       rewriting. This is important because the rewriting process is
 236       primarily used to rewrite logical URLs to physical
 237       pathnames.</p>
 238
 239       <p><strong>Example:</strong></p>
 240
 241 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 242 <pre>
 243 SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
 244 SCRIPT_FILENAME=/u/rse/.www/index.html
 245 SCRIPT_URL=/u/rse/
 246 SCRIPT_URI=http://en1.engelschall.com/u/rse/
 247 </pre>
 248 </code></td></tr></table></blockquote>
 249
 250 <h2><a name="Solutions">Practical Solutions</a></h2>
 251
 252       <p>We also have an <a href="../misc/rewriteguide.html">URL
 253       Rewriting Guide</a> available, which provides a collection of
 254       practical solutions for URL-based problems. There you can
 255       find real-life rulesets and additional information about
 256       mod_rewrite.</p>
 257 <hr/><h2><a name="RewriteBase">RewriteBase</a> <a name="rewritebase">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description: </strong></td><td>Sets the base URL for per-directory rewrites</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>RewriteBase <em>URL-path</em></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>See usage for information.</code></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:</a></td><td>directory, .htaccess</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Override" class="help">Override:</a></td><td>FileInfo</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Extension</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_rewrite</td></tr></table></td></tr></table>
 258       <p>The <code class="directive">RewriteBase</code> directive explicitly
 259       sets the base URL for per-directory rewrites. As you will see
 260       below, <a href="#rewriterule" class="directive"><code class="directive">RewriteRule</code></a>
 261       can be used in per-directory config files
 262       (<code>.htaccess</code>). There it will act locally,
 263       <em>i.e.</em>, the local directory prefix is stripped at this
 264       stage of processing and your rewriting rules act only on the
 265       remainder. At the end it is automatically added back to the
 266       path. The default setting is; <code class="directive">RewriteBase</code> <em>physical-directory-path</em></p>
 267
 268       <p>When a substitution occurs for a new URL, this module has
 269       to re-inject the URL into the server processing. To be able
 270       to do this it needs to know what the corresponding URL-prefix
 271       or URL-base is. By default this prefix is the corresponding
 272       filepath itself. <strong>But at most websites URLs are NOT
 273       directly related to physical filename paths, so this
 274       assumption will usually be wrong!</strong> There you have to
 275       use the <code>RewriteBase</code> directive to specify the
 276       correct URL-prefix.</p>
 277
 278 <blockquote><table><tr><td bgcolor="#e0e5f5"> If your webserver's URLs are <strong>not</strong> directly
 279 related to physical file paths, you have to use
 280 <code class="directive">RewriteBase</code> in every <code>.htaccess</code>
 281 files where you want to use <a href="#rewriterule" class="directive"><code class="directive">RewriteRule</code></a> directives.
 282 </td></tr></table></blockquote>
 283
 284         <p> For example, assume the following per-directory config file:</p>
 285
 286 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 287 <pre>
 288 #
 289 #  /abc/def/.htaccess -- per-dir config file for directory /abc/def
 290 #  Remember: /abc/def is the physical path of /xyz, <em>i.e.</em>, the server
 291 #            has a 'Alias /xyz /abc/def' directive <em>e.g.</em>
 292 #
 293
 294 RewriteEngine On
 295
 296 #  let the server know that we were reached via /xyz and not
 297 #  via the physical path prefix /abc/def
 298 RewriteBase   /xyz
 299
 300 #  now the rewriting rules
 301 RewriteRule   ^oldstuff\.html$  newstuff.html
 302 </pre>
 303 </code></td></tr></table></blockquote>
 304
 305         <p>In the above example, a request to
 306         <code>/xyz/oldstuff.html</code> gets correctly rewritten to
 307         the physical file <code>/abc/def/newstuff.html</code>.</p>
 308
 309 <blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>For Apache Hackers</strong></p>
 310 <p>The following list gives detailed information about
 311               the internal processing steps:</p>
 312 <pre>
 313 Request:
 314   /xyz/oldstuff.html
 315
 316 Internal Processing:
 317   /xyz/oldstuff.html     -&gt; /abc/def/oldstuff.html  (per-server Alias)
 318   /abc/def/oldstuff.html -&gt; /abc/def/newstuff.html  (per-dir    RewriteRule)
 319   /abc/def/newstuff.html -&gt; /xyz/newstuff.html      (per-dir    RewriteBase)
 320   /xyz/newstuff.html     -&gt; /abc/def/newstuff.html  (per-server Alias)
 321
 322 Result:
 323   /abc/def/newstuff.html
 324 </pre>
 325               <p>This seems very complicated but is
 326               the correct Apache internal processing, because the
 327               per-directory rewriting comes too late in the
 328               process. So, when it occurs the (rewritten) request
 329               has to be re-injected into the Apache kernel! BUT:
 330               While this seems like a serious overhead, it really
 331               isn't, because this re-injection happens fully
 332               internally to the Apache server and the same
 333               procedure is used by many other operations inside
 334               Apache. So, you can be sure the design and
 335               implementation is correct.</p>
 336 </td></tr></table></blockquote>
 337
 338 <hr/><h2><a name="RewriteCond">RewriteCond</a> <a name="rewritecond">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description: </strong></td><td>Defines a condition under which rewriting will take place
 339 </td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td> RewriteCond
 340       <em>TestString</em> <em>CondPattern</em></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>None</code></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config, virtual host, directory, .htaccess</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Override" class="help">Override:</a></td><td>FileInfo</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Extension</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_rewrite</td></tr></table></td></tr></table>
 341       <p>The <code class="directive">RewriteCond</code> directive defines a
 342       rule condition. Precede a <a href="#rewriterule" class="directive"><code class="directive">RewriteRule</code></a> directive with one
 343       or more <code class="directive">RewriteCond</code> directives. The following
 344       rewriting rule is only used if its pattern matches the current
 345       state of the URI <strong>and</strong> if these additional
 346       conditions apply too.</p>
 347
 348       <p><em>TestString</em> is a string which can contains the
 349       following expanded constructs in addition to plain text:</p>
 350
 351       <ul>
 352         <li>
 353           <strong>RewriteRule backreferences</strong>: These are
 354           backreferences of the form
 355
 356           <blockquote>
 357             <strong><code>$N</code></strong>
 358           </blockquote>
 359           (0 &lt;= N &lt;= 9) which provide access to the grouped
 360           parts (parenthesis!) of the pattern from the
 361           corresponding <code>RewriteRule</code> directive (the one
 362           following the current bunch of <code>RewriteCond</code>
 363           directives).
 364         </li>
 365
 366         <li>
 367           <strong>RewriteCond backreferences</strong>: These are
 368           backreferences of the form
 369
 370           <blockquote>
 371             <strong><code>%N</code></strong>
 372           </blockquote>
 373           (1 &lt;= N &lt;= 9) which provide access to the grouped
 374           parts (parentheses!) of the pattern from the last matched
 375           <code>RewriteCond</code> directive in the current bunch
 376           of conditions.
 377         </li>
 378
 379         <li>
 380           <strong>RewriteMap expansions</strong>: These are
 381           expansions of the form
 382
 383           <blockquote>
 384             <strong><code>${mapname:key|default}</code></strong>
 385           </blockquote>
 386           See <a href="#mapfunc">the documentation for
 387           RewriteMap</a> for more details.
 388         </li>
 389
 390         <li>
 391           <strong>Server-Variables</strong>: These are variables of
 392           the form
 393
 394           <blockquote>
 395             <strong><code>%{</code> <em>NAME_OF_VARIABLE</em>
 396             <code>}</code></strong>
 397           </blockquote>
 398           where <em>NAME_OF_VARIABLE</em> can be a string taken
 399           from the following list:
 400
 401           <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5">
 402             <tr>
 403               <td>
 404                 <strong>HTTP headers:</strong>
 405
 406                 <p>HTTP_USER_AGENT<br>
 407                  HTTP_REFERER<br>
 408                  HTTP_COOKIE<br>
 409                  HTTP_FORWARDED<br>
 410                  HTTP_HOST<br>
 411                  HTTP_PROXY_CONNECTION<br>
 412                  HTTP_ACCEPT<br>
 413                 </p>
 414               </td>
 415
 416               <td>
 417                 <strong>connection &amp; request:</strong>
 418
 419                 <p>REMOTE_ADDR<br>
 420                  REMOTE_HOST<br>
 421                  REMOTE_USER<br>
 422                  REMOTE_IDENT<br>
 423                  REQUEST_METHOD<br>
 424                  SCRIPT_FILENAME<br>
 425                  PATH_INFO<br>
 426                  QUERY_STRING<br>
 427                  AUTH_TYPE<br>
 428                 </p>
 429               </td>
 430             </tr>
 431
 432             <tr>
 433               <td>
 434                 <strong>server internals:</strong>
 435
 436                 <p>DOCUMENT_ROOT<br>
 437                  SERVER_ADMIN<br>
 438                  SERVER_NAME<br>
 439                  SERVER_ADDR<br>
 440                  SERVER_PORT<br>
 441                  SERVER_PROTOCOL<br>
 442                  SERVER_SOFTWARE<br>
 443                 </p>
 444               </td>
 445
 446               <td>
 447                 <strong>system stuff:</strong>
 448
 449                 <p>TIME_YEAR<br>
 450                  TIME_MON<br>
 451                  TIME_DAY<br>
 452                  TIME_HOUR<br>
 453                  TIME_MIN<br>
 454                  TIME_SEC<br>
 455                  TIME_WDAY<br>
 456                  TIME<br>
 457                 </p>
 458               </td>
 459
 460               <td>
 461                 <strong>specials:</strong>
 462
 463                 <p>API_VERSION<br>
 464                  THE_REQUEST<br>
 465                  REQUEST_URI<br>
 466                  REQUEST_FILENAME<br>
 467                  IS_SUBREQ<br>
 468                 </p>
 469               </td>
 470             </tr>
 471           </table>
 472
 473 <blockquote><table><tr><td bgcolor="#e0e5f5">
 474                 <p>These variables all
 475                 correspond to the similarly named HTTP
 476                 MIME-headers, C variables of the Apache server or
 477                 <code>struct tm</code> fields of the Unix system.
 478                 Most are documented elsewhere in the Manual or in
 479                 the CGI specification. Those that are special to
 480                 mod_rewrite include:</p>
 481
 482                 <dl>
 483                   <dt><code>IS_SUBREQ</code></dt>
 484
 485                   <dd>Will contain the text "true" if the request
 486                   currently being processed is a sub-request,
 487                   "false" otherwise. Sub-requests may be generated
 488                   by modules that need to resolve additional files
 489                   or URIs in order to complete their tasks.</dd>
 490
 491                   <dt><code>API_VERSION</code></dt>
 492
 493                   <dd>This is the version of the Apache module API
 494                   (the internal interface between server and
 495                   module) in the current httpd build, as defined in
 496                   include/ap_mmn.h. The module API version
 497                   corresponds to the version of Apache in use (in
 498                   the release version of Apache 1.3.14, for
 499                   instance, it is 19990320:10), but is mainly of
 500                   interest to module authors.</dd>
 501
 502                   <dt><code>THE_REQUEST</code></dt>
 503
 504                   <dd>The full HTTP request line sent by the
 505                   browser to the server (e.g., "<code>GET
 506                   /index.html HTTP/1.1</code>"). This does not
 507                   include any additional headers sent by the
 508                   browser.</dd>
 509
 510                   <dt><code>REQUEST_URI</code></dt>
 511
 512                   <dd>The resource requested in the HTTP request
 513                   line. (In the example above, this would be
 514                   "/index.html".)</dd>
 515
 516                   <dt><code>REQUEST_FILENAME</code></dt>
 517
 518                   <dd>The full local filesystem path to the file or
 519                   script matching the request.</dd>
 520                 </dl>
 521 </td></tr></table></blockquote>
 522         </li>
 523       </ul>
 524
 525       <p>Special Notes:</p>
 526
 527       <ol>
 528         <li>The variables SCRIPT_FILENAME and REQUEST_FILENAME
 529         contain the same value, <em>i.e.</em>, the value of the
 530         <code>filename</code> field of the internal
 531         <code>request_rec</code> structure of the Apache server.
 532         The first name is just the commonly known CGI variable name
 533         while the second is the consistent counterpart to
 534         REQUEST_URI (which contains the value of the
 535         <code>uri</code> field of <code>request_rec</code>).</li>
 536
 537         <li>There is the special format:
 538         <code>%{ENV:variable}</code> where <em>variable</em> can be
 539         any environment variable. This is looked-up via internal
 540         Apache structures and (if not found there) via
 541         <code>getenv()</code> from the Apache server process.</li>
 542
 543         <li>There is the special format:
 544         <code>%{HTTP:header}</code> where <em>header</em> can be
 545         any HTTP MIME-header name. This is looked-up from the HTTP
 546         request. Example: <code>%{HTTP:Proxy-Connection}</code> is
 547         the value of the HTTP header
 548         ``<code>Proxy-Connection:</code>''.</li>
 549
 550         <li>There is the special format
 551         <code>%{LA-U:variable}</code> for look-aheads which perform
 552         an internal (URL-based) sub-request to determine the final
 553         value of <em>variable</em>. Use this when you want to use a
 554         variable for rewriting which is actually set later in an
 555         API phase and thus is not available at the current stage.
 556         For instance when you want to rewrite according to the
 557         <code>REMOTE_USER</code> variable from within the
 558         per-server context (<code>httpd.conf</code> file) you have
 559         to use <code>%{LA-U:REMOTE_USER}</code> because this
 560         variable is set by the authorization phases which come
 561         <em>after</em> the URL translation phase where mod_rewrite
 562         operates. On the other hand, because mod_rewrite implements
 563         its per-directory context (<code>.htaccess</code> file) via
 564         the Fixup phase of the API and because the authorization
 565         phases come <em>before</em> this phase, you just can use
 566         <code>%{REMOTE_USER}</code> there.</li>
 567
 568         <li>There is the special format:
 569         <code>%{LA-F:variable}</code> which performs an internal
 570         (filename-based) sub-request to determine the final value
 571         of <em>variable</em>. Most of the time this is the same as
 572         LA-U above.</li>
 573       </ol>
 574
 575       <p><em>CondPattern</em> is the condition pattern,
 576       <em>i.e.</em>, a regular expression which is applied to the
 577       current instance of the <em>TestString</em>, <em>i.e.</em>,
 578       <em>TestString</em> is evaluated and then matched against
 579       <em>CondPattern</em>.</p>
 580
 581       <p><strong>Remember:</strong> <em>CondPattern</em> is a
 582       standard <em>Extended Regular Expression</em> with some
 583       additions:</p>
 584
 585       <ol>
 586         <li>You can prefix the pattern string with a
 587         '<code>!</code>' character (exclamation mark) to specify a
 588         <strong>non</strong>-matching pattern.</li>
 589
 590         <li>
 591           There are some special variants of <em>CondPatterns</em>.
 592           Instead of real regular expression strings you can also
 593           use one of the following:
 594
 595           <ul>
 596             <li>'<strong>&lt;CondPattern</strong>' (is lexically
 597             lower)<br>
 598              Treats the <em>CondPattern</em> as a plain string and
 599             compares it lexically to <em>TestString</em>. True if
 600             <em>TestString</em> is lexically lower than
 601             <em>CondPattern</em>.</li>
 602
 603             <li>'<strong>&gt;CondPattern</strong>' (is lexically
 604             greater)<br>
 605              Treats the <em>CondPattern</em> as a plain string and
 606             compares it lexically to <em>TestString</em>. True if
 607             <em>TestString</em> is lexically greater than
 608             <em>CondPattern</em>.</li>
 609
 610             <li>'<strong>=CondPattern</strong>' (is lexically
 611             equal)<br>
 612              Treats the <em>CondPattern</em> as a plain string and
 613             compares it lexically to <em>TestString</em>. True if
 614             <em>TestString</em> is lexically equal to
 615             <em>CondPattern</em>, i.e the two strings are exactly
 616             equal (character by character). If <em>CondPattern</em>
 617             is just <code>""</code> (two quotation marks) this
 618             compares <em>TestString</em> to the empty string.</li>
 619
 620             <li>'<strong>-d</strong>' (is
 621             <strong>d</strong>irectory)<br>
 622              Treats the <em>TestString</em> as a pathname and tests
 623             if it exists and is a directory.</li>
 624
 625             <li>'<strong>-f</strong>' (is regular
 626             <strong>f</strong>ile)<br>
 627              Treats the <em>TestString</em> as a pathname and tests
 628             if it exists and is a regular file.</li>
 629
 630             <li>'<strong>-s</strong>' (is regular file with
 631             <strong>s</strong>ize)<br>
 632              Treats the <em>TestString</em> as a pathname and tests
 633             if it exists and is a regular file with size greater
 634             than zero.</li>
 635
 636             <li>'<strong>-l</strong>' (is symbolic
 637             <strong>l</strong>ink)<br>
 638              Treats the <em>TestString</em> as a pathname and tests
 639             if it exists and is a symbolic link.</li>
 640
 641             <li>'<strong>-F</strong>' (is existing file via
 642             subrequest)<br>
 643              Checks if <em>TestString</em> is a valid file and
 644             accessible via all the server's currently-configured
 645             access controls for that path. This uses an internal
 646             subrequest to determine the check, so use it with care
 647             because it decreases your servers performance!</li>
 648
 649             <li>'<strong>-U</strong>' (is existing URL via
 650             subrequest)<br>
 651              Checks if <em>TestString</em> is a valid URL and
 652             accessible via all the server's currently-configured
 653             access controls for that path. This uses an internal
 654             subrequest to determine the check, so use it with care
 655             because it decreases your server's performance!</li>
 656           </ul>
 657
 658 <blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>Notice</strong></p>
 659               All of these tests can
 660               also be prefixed by an exclamation mark ('!') to
 661               negate their meaning.
 662 </td></tr></table></blockquote>
 663         </li>
 664       </ol>
 665
 666       <p>Additionally you can set special flags for
 667       <em>CondPattern</em> by appending</p>
 668
 669       <blockquote>
 670         <strong><code>[</code><em>flags</em><code>]</code></strong>
 671       </blockquote>
 672
 673       <p>as the third argument to the <code>RewriteCond</code>
 674       directive. <em>Flags</em> is a comma-separated list of the
 675       following flags:</p>
 676
 677       <ul>
 678         <li>'<strong><code>nocase|NC</code></strong>'
 679         (<strong>n</strong>o <strong>c</strong>ase)<br>
 680          This makes the test case-insensitive, <em>i.e.</em>, there
 681         is no difference between 'A-Z' and 'a-z' both in the
 682         expanded <em>TestString</em> and the <em>CondPattern</em>.
 683         This flag is effective only for comparisons between
 684         <em>TestString</em> and <em>CondPattern</em>. It has no
 685         effect on filesystem and subrequest checks.</li>
 686
 687         <li>
 688           '<strong><code>ornext|OR</code></strong>'
 689           (<strong>or</strong> next condition)<br>
 690            Use this to combine rule conditions with a local OR
 691           instead of the implicit AND. Typical example:
 692
 693 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 694 <pre>
 695 RewriteCond %{REMOTE_HOST}  ^host1.*  [OR]
 696 RewriteCond %{REMOTE_HOST}  ^host2.*  [OR]
 697 RewriteCond %{REMOTE_HOST}  ^host3.*
 698 RewriteRule ...some special stuff for any of these hosts...
 699 </pre>
 700 </code></td></tr></table></blockquote>
 701
 702           Without this flag you would have to write the cond/rule
 703           three times.
 704         </li>
 705       </ul>
 706
 707       <p><strong>Example:</strong></p>
 708
 709        <p>To rewrite the Homepage of a site according to the
 710         ``<code>User-Agent:</code>'' header of the request, you can
 711         use the following: </p>
 712
 713 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 714 <pre>
 715 RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
 716 RewriteRule  ^/$                 /homepage.max.html  [L]
 717
 718 RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
 719 RewriteRule  ^/$                 /homepage.min.html  [L]
 720
 721 RewriteRule  ^/$                 /homepage.std.html  [L]
 722 </pre>
 723 </code></td></tr></table></blockquote>
 724
 725         <p>Interpretation: If you use Netscape Navigator as your
 726         browser (which identifies itself as 'Mozilla'), then you
 727         get the max homepage, which includes Frames, <em>etc.</em>
 728         If you use the Lynx browser (which is Terminal-based), then
 729         you get the min homepage, which contains no images, no
 730         tables, <em>etc.</em> If you use any other browser you get
 731         the standard homepage.</p>
 732
 733 <hr/><h2><a name="RewriteEngine">RewriteEngine</a> <a name="rewriteengine">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description: </strong></td><td>Enables or disables runtime rewriting engine</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>RewriteEngine on|off</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>RewriteEngine off</code></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config, virtual host, directory, .htaccess</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Override" class="help">Override:</a></td><td>FileInfo</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Extension</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_rewrite</td></tr></table></td></tr></table>
 734
 735       <p>The <code class="directive">RewriteEngine</code> directive enables or
 736       disables the runtime rewriting engine. If it is set to
 737       <code>off</code> this module does no runtime processing at
 738       all. It does not even update the <code>SCRIPT_URx</code>
 739       environment variables.</p>
 740
 741       <p>Use this directive to disable the module instead of
 742       commenting out all the <a href="#rewriterule" class="directive"><code class="directive">RewriteRule</code></a> directives!</p>
 743
 744       <p>Note that, by default, rewrite configurations are not
 745       inherited. This means that you need to have a
 746       <code>RewriteEngine on</code> directive for each virtual host
 747       in which you wish to use it.</p>
 748 <hr/><h2><a name="RewriteLock">RewriteLock</a> <a name="rewritelock">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description: </strong></td><td>Sets the name of the lock file used for RewriteMap
 749 synchronization</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>RewriteLock <em>file-path</em></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>None</code></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Extension</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_rewrite</td></tr></table></td></tr></table>
 750       <p>This directive sets the filename for a synchronization
 751       lockfile which mod_rewrite needs to communicate with <a href="#rewritemap" class="directive"><code class="directive">RewriteMap</code></a>
 752       <em>programs</em>. Set this lockfile to a local path (not on a
 753       NFS-mounted device) when you want to use a rewriting
 754       map-program. It is not required for other types of rewriting
 755       maps.</p>
 756 <hr/><h2><a name="RewriteLog">RewriteLog</a> <a name="rewritelog">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description: </strong></td><td>Sets the name of the file used for logging rewrite engine
 757 processing</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>RewriteLog <em>file-path</em></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config, virtual host</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Extension</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_rewrite</td></tr></table></td></tr></table>
 758       <p>The <code class="directive">RewriteLog</code> directive sets the name
 759       of the file to which the server logs any rewriting actions it
 760       performs. If the name does not begin with a slash
 761       ('<code>/</code>') then it is assumed to be relative to the
 762       <em>Server Root</em>. The directive should occur only once per
 763       server config.</p>
 764
 765 <blockquote><table><tr><td bgcolor="#e0e5f5">    To disable the logging of
 766           rewriting actions it is not recommended to set
 767           <em>Filename</em> to <code>/dev/null</code>, because
 768           although the rewriting engine does not then output to a
 769           logfile it still creates the logfile output internally.
 770           <strong>This will slow down the server with no advantage
 771           to the administrator!</strong> To disable logging either
 772           remove or comment out the <code class="directive">RewriteLog</code>
 773           directive or use <code>RewriteLogLevel 0</code>!
 774 </td></tr></table></blockquote>
 775
 776 <blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>Security</strong></p>
 777
 778 See the <a href="../misc/security_tips.html">Apache Security Tips</a>
 779 document for details on why your security could be compromised if the
 780 directory where logfiles are stored is writable by anyone other than
 781 the user that starts the server.
 782 </td></tr></table></blockquote>
 783
 784 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><p align="center"><strong>Example</strong></p><code>
 785 RewriteLog "/usr/local/var/apache/logs/rewrite.log"
 786 </code></td></tr></table></blockquote>
 787
 788 <hr/><h2><a name="RewriteLogLevel">RewriteLogLevel</a> <a name="rewriteloglevel">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description: </strong></td><td>Sets the verbosity of the log file used by the rewrite
 789 engine</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>RewriteLogLevel <em>Level</em></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>RerwiteLogLevel 0</code></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config, virtual host</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Extension</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_rewrite</td></tr></table></td></tr></table>
 790       <p>The <code class="directive">RewriteLogLevel</code> directive sets the
 791       verbosity level of the rewriting logfile. The default level 0
 792       means no logging, while 9 or more means that practically all
 793       actions are logged.</p>
 794
 795       <p>To disable the logging of rewriting actions simply set
 796       <em>Level</em> to 0. This disables all rewrite action
 797       logs.</p>
 798
 799 <blockquote><table><tr><td bgcolor="#e0e5f5"> Using a high value for
 800           <em>Level</em> will slow down your Apache server
 801           dramatically! Use the rewriting logfile at a
 802           <em>Level</em> greater than 2 only for debugging!
 803 </td></tr></table></blockquote>
 804
 805 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><p align="center"><strong>Example</strong></p><code>
 806 RewriteLogLevel 3
 807 </code></td></tr></table></blockquote>
 808
 809 <hr/><h2><a name="RewriteMap">RewriteMap</a> <a name="rewritemap">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description: </strong></td><td>Defines a mapping function for key-lookup</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
 810 </td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>None</code></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config, virtual host</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Extension</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_rewrite</td></tr></table></td></tr></table>
 811       <p>The <code class="directive">RewriteMap</code> directive defines a
 812       <em>Rewriting Map</em> which can be used inside rule
 813       substitution strings by the mapping-functions to
 814       insert/substitute fields through a key lookup. The source of
 815       this lookup can be of various types.</p>
 816
 817       <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
 818       the name of the map and will be used to specify a
 819       mapping-function for the substitution strings of a rewriting
 820       rule via one of the following constructs:</p>
 821
 822       <blockquote>
 823         <strong><code>${</code> <em>MapName</em> <code>:</code>
 824         <em>LookupKey</em> <code>}</code><br>
 825          <code>${</code> <em>MapName</em> <code>:</code>
 826         <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
 827         <code>}</code></strong>
 828       </blockquote>
 829
 830       <p>When such a construct occurs the map <em>MapName</em> is
 831       consulted and the key <em>LookupKey</em> is looked-up. If the
 832       key is found, the map-function construct is substituted by
 833       <em>SubstValue</em>. If the key is not found then it is
 834       substituted by <em>DefaultValue</em> or by the empty string
 835       if no <em>DefaultValue</em> was specified.</p>
 836
 837       <p>The following combinations for <em>MapType</em> and
 838       <em>MapSource</em> can be used:</p>
 839
 840       <ul>
 841         <li>
 842           <strong>Standard Plain Text</strong><br>
 843            MapType: <code>txt</code>, MapSource: Unix filesystem
 844           path to valid regular file
 845
 846           <p>This is the standard rewriting map feature where the
 847           <em>MapSource</em> is a plain ASCII file containing
 848           either blank lines, comment lines (starting with a '#'
 849           character) or pairs like the following - one per
 850           line.</p>
 851
 852           <blockquote>
 853             <strong><em>MatchingKey</em>
 854             <em>SubstValue</em></strong>
 855           </blockquote>
 856
 857 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><p align="center"><strong>Example</strong></p><code>
 858 <pre>
 859 ##
 860 ##  map.txt -- rewriting map
 861 ##
 862
 863 Ralf.S.Engelschall    rse   # Bastard Operator From Hell
 864 Mr.Joe.Average        joe   # Mr. Average
 865 </pre>
 866 </code></td></tr></table></blockquote>
 867
 868 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 869 RewriteMap real-to-user txt:/path/to/file/map.txt
 870 </code></td></tr></table></blockquote>
 871         </li>
 872
 873         <li>
 874           <strong>Randomized Plain Text</strong><br>
 875            MapType: <code>rnd</code>, MapSource: Unix filesystem
 876           path to valid regular file
 877
 878           <p>This is identical to the Standard Plain Text variant
 879           above but with a special post-processing feature: After
 880           looking up a value it is parsed according to contained
 881           ``<code>|</code>'' characters which have the meaning of
 882           ``or''. In other words they indicate a set of
 883           alternatives from which the actual returned value is
 884           chosen randomly. Although this sounds crazy and useless,
 885           it was actually designed for load balancing in a reverse
 886           proxy situation where the looked up values are server
 887           names. Example:</p>
 888
 889 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 890 <pre>
 891 ##
 892 ##  map.txt -- rewriting map
 893 ##
 894
 895 static   www1|www2|www3|www4
 896 dynamic  www5|www6
 897 </pre>
 898 </code></td></tr></table></blockquote>
 899
 900 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 901 RewriteMap servers rnd:/path/to/file/map.txt
 902 </code></td></tr></table></blockquote>
 903         </li>
 904
 905         <li>
 906           <strong>Hash File</strong><br>
 907            MapType: <code>dbm</code>, MapSource: Unix filesystem
 908           path to valid regular file
 909
 910           <p>Here the source is a binary NDBM format file
 911           containing the same contents as a <em>Plain Text</em>
 912           format file, but in a special representation which is
 913           optimized for really fast lookups. You can create such a
 914           file with any NDBM tool or with the following Perl
 915           script:</p>
 916
 917 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 918 <pre>
 919 #!/path/to/bin/perl
 920 ##
 921 ##  txt2dbm -- convert txt map to dbm format
 922 ##
 923
 924 use NDBM_File;
 925 use Fcntl;
 926
 927 ($txtmap, $dbmmap) = @ARGV;
 928
 929 open(TXT, "&lt;$txtmap") or die "Couldn't open $txtmap!\n";
 930 tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644) or die "Couldn't create $dbmmap!\n";
 931
 932 while (&lt;TXT&gt;) {
 933   next if (/^\s*#/ or /^\s*$/);
 934   $DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/);
 935 }
 936
 937 untie %DB;
 938 close(TXT);
 939 </pre>
 940 </code></td></tr></table></blockquote>
 941
 942 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 943 $ txt2dbm map.txt map.db
 944 </code></td></tr></table></blockquote>
 945         </li>
 946
 947         <li>
 948           <strong>Internal Function</strong><br>
 949            MapType: <code>int</code>, MapSource: Internal Apache
 950           function
 951
 952           <p>Here the source is an internal Apache function.
 953           Currently you cannot create your own, but the following
 954           functions already exists:</p>
 955
 956           <ul>
 957             <li><strong>toupper</strong>:<br>
 958              Converts the looked up key to all upper case.</li>
 959
 960             <li><strong>tolower</strong>:<br>
 961              Converts the looked up key to all lower case.</li>
 962
 963             <li><strong>escape</strong>:<br>
 964              Translates special characters in the looked up key to
 965             hex-encodings.</li>
 966
 967             <li><strong>unescape</strong>:<br>
 968              Translates hex-encodings in the looked up key back to
 969             special characters.</li>
 970           </ul>
 971         </li>
 972
 973         <li>
 974           <strong>External Rewriting Program</strong><br>
 975            MapType: <code>prg</code>, MapSource: Unix filesystem
 976           path to valid regular file
 977
 978           <p>Here the source is a program, not a map file. To
 979           create it you can use the language of your choice, but
 980           the result has to be a executable (<em>i.e.</em>, either
 981           object-code or a script with the magic cookie trick
 982           '<code>#!/path/to/interpreter</code>' as the first
 983           line).</p>
 984
 985           <p>This program is started once at startup of the Apache
 986           servers and then communicates with the rewriting engine
 987           over its <code>stdin</code> and <code>stdout</code>
 988           file-handles. For each map-function lookup it will
 989           receive the key to lookup as a newline-terminated string
 990           on <code>stdin</code>. It then has to give back the
 991           looked-up value as a newline-terminated string on
 992           <code>stdout</code> or the four-character string
 993           ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there
 994           is no corresponding value for the given key). A trivial
 995           program which will implement a 1:1 map (<em>i.e.</em>,
 996           key == value) could be:</p>
 997
 998 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 999 <pre>
1000 #!/usr/bin/perl
1001 $| = 1;
1002 while (&lt;STDIN&gt;) {
1003     # ...put here any transformations or lookups...
1004     print $_;
1005 }
1006 </pre>
1007 </code></td></tr></table></blockquote>
1008
1009           <p>But be very careful:</p>
1010
1011           <ol>
1012             <li>``<em>Keep it simple, stupid</em>'' (KISS), because
1013             if this program hangs it will hang the Apache server
1014             when the rule occurs.</li>
1015
1016             <li>Avoid one common mistake: never do buffered I/O on
1017             <code>stdout</code>! This will cause a deadloop! Hence
1018             the ``<code>$|=1</code>'' in the above example...</li>
1019
1020             <li>Use the <a href="#rewritelock" class="directive"><code class="directive">RewriteLock</code></a> directive to
1021             define a lockfile mod_rewrite can use to synchronize the
1022             communication to the program. By default no such
1023             synchronization takes place.</li>
1024           </ol>
1025         </li>
1026       </ul>
1027       <p>The <code class="directive">RewriteMap</code> directive can occur more than
1028       once. For each mapping-function use one
1029       <code class="directive">RewriteMap</code> directive to declare its rewriting
1030       mapfile. While you cannot <strong>declare</strong> a map in
1031       per-directory context it is of course possible to
1032       <strong>use</strong> this map in per-directory context. </p>
1033
1034 <blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>Note</strong></p> For plain text and DBM format files the
1035 looked-up keys are cached in-core until the <code>mtime</code> of the
1036 mapfile changes or the server does a restart. This way you can have
1037 map-functions in rules which are used for <strong>every</strong>
1038 request.  This is no problem, because the external lookup only happens
1039 once!
1040 </td></tr></table></blockquote>
1041
1042 <hr/><h2><a name="RewriteOptions">RewriteOptions</a> <a name="rewriteoptions">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description: </strong></td><td>Sets some special options for the rewrite engine</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>RewriteOptions <em>Options</em></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>None</code></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config, virtual host, directory, .htaccess</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Extension</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_rewrite</td></tr></table></td></tr></table>
1043
1044       <p>The <code class="directive">RewriteOptions</code> directive sets some
1045       special options for the current per-server or per-directory
1046       configuration. The <em>Option</em> strings can be one of the
1047       following:</p>
1048
1049       <ul>
1050         <li>'<strong><code>inherit</code></strong>'<br>
1051          This forces the current configuration to inherit the
1052         configuration of the parent. In per-virtual-server context
1053         this means that the maps, conditions and rules of the main
1054         server are inherited. In per-directory context this means
1055         that conditions and rules of the parent directory's
1056         <code>.htaccess</code> configuration are inherited.</li>
1057       </ul>
1058 <hr/><h2><a name="RewriteRule">RewriteRule</a> <a name="rewriterule">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description: </strong></td><td>Defines rules for the rewriting engine</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>RewriteRule
1059       <em>Pattern</em> <em>Substitution</em></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>None</code></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config, virtual host, directory, .htaccess</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Override" class="help">Override:</a></td><td>FileInfo</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Extension</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_rewrite</td></tr></table></td></tr></table>
1060       <p>The <code class="directive">RewriteRule</code> directive is the real
1061       rewriting workhorse. The directive can occur more than once.
1062       Each directive then defines one single rewriting rule. The
1063       <strong>definition order</strong> of these rules is
1064       <strong>important</strong>, because this order is used when
1065       applying the rules at run-time.</p>
1066
1067       <p><a id="patterns" name="patterns"><em>Pattern</em></a> can
1068       be (for Apache 1.1.x a System V8 and for Apache 1.2.x and
1069       later a POSIX) <a id="regexp" name="regexp">regular
1070       expression</a> which gets applied to the current URL. Here
1071       ``current'' means the value of the URL when this rule gets
1072       applied. This may not be the originally requested URL,
1073       because any number of rules may already have matched and made
1074       alterations to it.</p>
1075
1076       <p>Some hints about the syntax of regular expressions:</p>
1077
1078       <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5">
1079         <tr>
1080           <td>
1081 <pre>
1082 <strong>Text:</strong>
1083   <strong><code>.</code></strong>           Any single character
1084   <strong><code>[</code></strong>chars<strong><code>]</code></strong>     Character class: One  of chars
1085   <strong><code>[^</code></strong>chars<strong><code>]</code></strong>    Character class: None of chars
1086   text1<strong><code>|</code></strong>text2 Alternative: text1 or text2
1087
1088 <strong>Quantifiers:</strong>
1089   <strong><code>?</code></strong>           0 or 1 of the preceding text
1090   <strong><code>*</code></strong>           0 or N of the preceding text (N &gt; 0)
1091   <strong><code>+</code></strong>           1 or N of the preceding text (N &gt; 1)
1092
1093 <strong>Grouping:</strong>
1094   <strong><code>(</code></strong>text<strong><code>)</code></strong>      Grouping of text
1095               (either to set the borders of an alternative or
1096               for making backreferences where the <strong>N</strong>th group can
1097               be used on the RHS of a RewriteRule with <code>$</code><strong>N</strong>)
1098
1099 <strong>Anchors:</strong>
1100   <strong><code>^</code></strong>           Start of line anchor
1101   <strong><code>$</code></strong>           End   of line anchor
1102
1103 <strong>Escaping:</strong>
1104   <strong><code>\</code></strong>char       escape that particular char
1105               (for instance to specify the chars "<code>.[]()</code>" <em>etc.</em>)
1106 </pre>
1107           </td>
1108         </tr>
1109       </table>
1110
1111       <p>For more information about regular expressions either have
1112       a look at your local regex(3) manpage or its
1113       <code>src/regex/regex.3</code> copy in the Apache 1.3
1114       distribution. If you are interested in more detailed
1115       information about regular expressions and their variants
1116       (POSIX regex, Perl regex, <em>etc.</em>) have a look at the
1117       following dedicated book on this topic:</p>
1118
1119       <blockquote>
1120         <em>Mastering Regular Expressions</em><br>
1121          Jeffrey E.F. Friedl<br>
1122          Nutshell Handbook Series<br>
1123          O'Reilly &amp; Associates, Inc. 1997<br>
1124          ISBN 1-56592-257-3<br>
1125       </blockquote>
1126
1127       <p>Additionally in mod_rewrite the NOT character
1128       ('<code>!</code>') is a possible pattern prefix. This gives
1129       you the ability to negate a pattern; to say, for instance:
1130       ``<em>if the current URL does <strong>NOT</strong> match this
1131       pattern</em>''. This can be used for exceptional cases, where
1132       it is easier to match the negative pattern, or as a last
1133       default rule.</p>
1134
1135 <blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>Notice</strong></p>
1136 When using the NOT character
1137           to negate a pattern you cannot have grouped wildcard
1138           parts in the pattern. This is impossible because when the
1139           pattern does NOT match, there are no contents for the
1140           groups. In consequence, if negated patterns are used, you
1141           cannot use <code>$N</code> in the substitution
1142           string!
1143 </td></tr></table></blockquote>
1144
1145       <p><a id="rhs" name="rhs"><em>Substitution</em></a> of a
1146       rewriting rule is the string which is substituted for (or
1147       replaces) the original URL for which <em>Pattern</em>
1148       matched. Beside plain text you can use</p>
1149
1150       <ol>
1151         <li>back-references <code>$N</code> to the RewriteRule
1152         pattern</li>
1153
1154         <li>back-references <code>%N</code> to the last matched
1155         RewriteCond pattern</li>
1156
1157         <li>server-variables as in rule condition test-strings
1158         (<code>%{VARNAME}</code>)</li>
1159
1160         <li><a href="#mapfunc">mapping-function</a> calls
1161         (<code>${mapname:key|default}</code>)</li>
1162       </ol>
1163       <p>Back-references are <code>$</code><strong>N</strong>
1164       (<strong>N</strong>=0..9) identifiers which will be replaced
1165       by the contents of the <strong>N</strong>th group of the
1166       matched <em>Pattern</em>. The server-variables are the same
1167       as for the <em>TestString</em> of a <code>RewriteCond</code>
1168       directive. The mapping-functions come from the
1169       <code>RewriteMap</code> directive and are explained there.
1170       These three types of variables are expanded in the order of
1171       the above list. </p>
1172
1173       <p>As already mentioned above, all the rewriting rules are
1174       applied to the <em>Substitution</em> (in the order of
1175       definition in the config file). The URL is <strong>completely
1176       replaced</strong> by the <em>Substitution</em> and the
1177       rewriting process goes on until there are no more rules
1178       unless explicitly terminated by a
1179       <code><strong>L</strong></code> flag - see below.</p>
1180
1181       <p>There is a special substitution string named
1182       '<code>-</code>' which means: <strong>NO
1183       substitution</strong>! Sounds silly? No, it is useful to
1184       provide rewriting rules which <strong>only</strong> match
1185       some URLs but do no substitution, <em>e.g.</em>, in
1186       conjunction with the <strong>C</strong> (chain) flag to be
1187       able to have more than one pattern to be applied before a
1188       substitution occurs.</p>
1189
1190       <p>One more note: You can even create URLs in the
1191       substitution string containing a query string part. Just use
1192       a question mark inside the substitution string to indicate
1193       that the following stuff should be re-injected into the
1194       QUERY_STRING. When you want to erase an existing query
1195       string, end the substitution string with just the question
1196       mark.</p>
1197
1198 <blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>Note</strong></p>
1199 There is a special feature:
1200           When you prefix a substitution field with
1201           <code>http://</code><em>thishost</em>[<em>:thisport</em>]
1202           then <strong>mod_rewrite</strong> automatically strips it
1203           out. This auto-reduction on implicit external redirect
1204           URLs is a useful and important feature when used in
1205           combination with a mapping-function which generates the
1206           hostname part. Have a look at the first example in the
1207           example section below to understand this.
1208 </td></tr></table></blockquote>
1209
1210 <blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>Remember</strong></p>
1211  An unconditional external
1212           redirect to your own server will not work with the prefix
1213           <code>http://thishost</code> because of this feature. To
1214           achieve such a self-redirect, you have to use the
1215           <strong>R</strong>-flag (see below).
1216 </td></tr></table></blockquote>
1217
1218       <p>Additionally you can set special flags for
1219       <em>Substitution</em> by appending</p>
1220
1221       <blockquote>
1222         <strong><code>[</code><em>flags</em><code>]</code></strong>
1223       </blockquote>
1224       <p>
1225       as the third argument to the <code>RewriteRule</code>
1226       directive. <em>Flags</em> is a comma-separated list of the
1227       following flags: </p>
1228
1229       <ul>
1230         <li>
1231           '<strong><code>redirect|R</code>
1232           [=<em>code</em>]</strong>' (force <a id="redirect" name="redirect"><strong>r</strong>edirect</a>)<br>
1233            Prefix <em>Substitution</em> with
1234           <code>http://thishost[:thisport]/</code> (which makes the
1235           new URL a URI) to force a external redirection. If no
1236           <em>code</em> is given a HTTP response of 302 (MOVED
1237           TEMPORARILY) is used. If you want to use other response
1238           codes in the range 300-400 just specify them as a number
1239           or use one of the following symbolic names:
1240           <code>temp</code> (default), <code>permanent</code>,
1241           <code>seeother</code>. Use it for rules which should
1242           canonicalize the URL and give it back to the client,
1243           <em>e.g.</em>, translate ``<code>/~</code>'' into
1244           ``<code>/u/</code>'' or always append a slash to
1245           <code>/u/</code><em>user</em>, etc.<br>
1246
1247
1248           <p><strong>Note:</strong> When you use this flag, make
1249           sure that the substitution field is a valid URL! If not,
1250           you are redirecting to an invalid location! And remember
1251           that this flag itself only prefixes the URL with
1252           <code>http://thishost[:thisport]/</code>, rewriting
1253           continues. Usually you also want to stop and do the
1254           redirection immediately. To stop the rewriting you also
1255           have to provide the 'L' flag.</p>
1256         </li>
1257
1258         <li>'<strong><code>forbidden|F</code></strong>' (force URL
1259         to be <strong>f</strong>orbidden)<br>
1260          This forces the current URL to be forbidden,
1261         <em>i.e.</em>, it immediately sends back a HTTP response of
1262         403 (FORBIDDEN). Use this flag in conjunction with
1263         appropriate RewriteConds to conditionally block some
1264         URLs.</li>
1265
1266         <li>'<strong><code>gone|G</code></strong>' (force URL to be
1267         <strong>g</strong>one)<br>
1268          This forces the current URL to be gone, <em>i.e.</em>, it
1269         immediately sends back a HTTP response of 410 (GONE). Use
1270         this flag to mark pages which no longer exist as gone.</li>
1271
1272         <li>
1273           '<strong><code>proxy|P</code></strong>' (force
1274           <strong>p</strong>roxy)<br>
1275            This flag forces the substitution part to be internally
1276           forced as a proxy request and immediately (<em>i.e.</em>,
1277           rewriting rule processing stops here) put through the <a href="mod_proxy.html">proxy module</a>. You have to make
1278           sure that the substitution string is a valid URI
1279           (<em>e.g.</em>, typically starting with
1280           <code>http://</code><em>hostname</em>) which can be
1281           handled by the Apache proxy module. If not you get an
1282           error from the proxy module. Use this flag to achieve a
1283           more powerful implementation of the <a href="mod_proxy.html#proxypass">ProxyPass</a> directive,
1284           to map some remote stuff into the namespace of the local
1285           server.
1286
1287           <p>Notice: To use this functionality make sure you have
1288           the proxy module compiled into your Apache server
1289           program. If you don't know please check whether
1290           <code>mod_proxy.c</code> is part of the ``<code>httpd
1291           -l</code>'' output. If yes, this functionality is
1292           available to mod_rewrite. If not, then you first have to
1293           rebuild the ``<code>httpd</code>'' program with mod_proxy
1294           enabled.</p>
1295         </li>
1296
1297         <li>'<strong><code>last|L</code></strong>'
1298         (<strong>l</strong>ast rule)<br>
1299          Stop the rewriting process here and don't apply any more
1300         rewriting rules. This corresponds to the Perl
1301         <code>last</code> command or the <code>break</code> command
1302         from the C language. Use this flag to prevent the currently
1303         rewritten URL from being rewritten further by following
1304         rules. For example, use it to rewrite the root-path URL
1305         ('<code>/</code>') to a real one, <em>e.g.</em>,
1306         '<code>/e/www/</code>'.</li>
1307
1308         <li>'<strong><code>next|N</code></strong>'
1309         (<strong>n</strong>ext round)<br>
1310          Re-run the rewriting process (starting again with the
1311         first rewriting rule). Here the URL to match is again not
1312         the original URL but the URL from the last rewriting rule.
1313         This corresponds to the Perl <code>next</code> command or
1314         the <code>continue</code> command from the C language. Use
1315         this flag to restart the rewriting process, <em>i.e.</em>,
1316         to immediately go to the top of the loop.<br>
1317          <strong>But be careful not to create an infinite
1318         loop!</strong></li>
1319
1320         <li>'<strong><code>chain|C</code></strong>'
1321         (<strong>c</strong>hained with next rule)<br>
1322          This flag chains the current rule with the next rule
1323         (which itself can be chained with the following rule,
1324         <em>etc.</em>). This has the following effect: if a rule
1325         matches, then processing continues as usual, <em>i.e.</em>,
1326         the flag has no effect. If the rule does
1327         <strong>not</strong> match, then all following chained
1328         rules are skipped. For instance, use it to remove the
1329         ``<code>.www</code>'' part inside a per-directory rule set
1330         when you let an external redirect happen (where the
1331         ``<code>.www</code>'' part should not to occur!).</li>
1332
1333         <li>
1334         '<strong><code>type|T</code></strong>=<em>MIME-type</em>'
1335         (force MIME <strong>t</strong>ype)<br>
1336          Force the MIME-type of the target file to be
1337         <em>MIME-type</em>. For instance, this can be used to
1338         simulate the <code>mod_alias</code> directive
1339         <code>ScriptAlias</code> which internally forces all files
1340         inside the mapped directory to have a MIME type of
1341         ``<code>application/x-httpd-cgi</code>''.</li>
1342
1343         <li>
1344           '<strong><code>nosubreq|NS</code></strong>' (used only if
1345           <strong>n</strong>o internal
1346           <strong>s</strong>ub-request)<br>
1347            This flag forces the rewriting engine to skip a
1348           rewriting rule if the current request is an internal
1349           sub-request. For instance, sub-requests occur internally
1350           in Apache when <code>mod_include</code> tries to find out
1351           information about possible directory default files
1352           (<code>index.xxx</code>). On sub-requests it is not
1353           always useful and even sometimes causes a failure to if
1354           the complete set of rules are applied. Use this flag to
1355           exclude some rules.<br>
1356
1357
1358           <p>Use the following rule for your decision: whenever you
1359           prefix some URLs with CGI-scripts to force them to be
1360           processed by the CGI-script, the chance is high that you
1361           will run into problems (or even overhead) on
1362           sub-requests. In these cases, use this flag.</p>
1363         </li>
1364
1365         <li>'<strong><code>nocase|NC</code></strong>'
1366         (<strong>n</strong>o <strong>c</strong>ase)<br>
1367          This makes the <em>Pattern</em> case-insensitive,
1368         <em>i.e.</em>, there is no difference between 'A-Z' and
1369         'a-z' when <em>Pattern</em> is matched against the current
1370         URL.</li>
1371
1372         <li>'<strong><code>qsappend|QSA</code></strong>'
1373         (<strong>q</strong>uery <strong>s</strong>tring
1374         <strong>a</strong>ppend)<br>
1375          This flag forces the rewriting engine to append a query
1376         string part in the substitution string to the existing one
1377         instead of replacing it. Use this when you want to add more
1378         data to the query string via a rewrite rule.</li>
1379
1380         <li>
1381           '<strong><code>noescape|NE</code></strong>'
1382           (<strong>n</strong>o URI <strong>e</strong>scaping of
1383           output)<br>
1384            This flag keeps mod_rewrite from applying the usual URI
1385           escaping rules to the result of a rewrite. Ordinarily,
1386           special characters (such as '%', '$', ';', and so on)
1387           will be escaped into their hexcode equivalents ('%25',
1388           '%24', and '%3B', respectively); this flag prevents this
1389           from being done. This allows percent symbols to appear in
1390           the output, as in
1391 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
1392     RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
1393 </code></td></tr></table></blockquote>
1394
1395           which would turn '<code>/foo/zed</code>' into a safe
1396           request for '<code>/bar?arg=P1=zed</code>'.
1397         </li>
1398
1399         <li>
1400           '<strong><code>passthrough|PT</code></strong>'
1401           (<strong>p</strong>ass <strong>t</strong>hrough to next
1402           handler)<br>
1403            This flag forces the rewriting engine to set the
1404           <code>uri</code> field of the internal
1405           <code>request_rec</code> structure to the value of the
1406           <code>filename</code> field. This flag is just a hack to
1407           be able to post-process the output of
1408           <code>RewriteRule</code> directives by
1409           <code>Alias</code>, <code>ScriptAlias</code>,
1410           <code>Redirect</code>, <em>etc.</em> directives from
1411           other URI-to-filename translators. A trivial example to
1412           show the semantics: If you want to rewrite
1413           <code>/abc</code> to <code>/def</code> via the rewriting
1414           engine of <code>mod_rewrite</code> and then
1415           <code>/def</code> to <code>/ghi</code> with
1416           <code>mod_alias</code>:
1417 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
1418     RewriteRule ^/abc(.*)  /def$1 [PT]<br>
1419     Alias       /def       /ghi
1420 </code></td></tr></table></blockquote>
1421           If you omit the <code>PT</code> flag then
1422           <code>mod_rewrite</code> will do its job fine,
1423           <em>i.e.</em>, it rewrites <code>uri=/abc/...</code> to
1424           <code>filename=/def/...</code> as a full API-compliant
1425           URI-to-filename translator should do. Then
1426           <code>mod_alias</code> comes and tries to do a
1427           URI-to-filename transition which will not work.
1428
1429           <p>Note: <strong>You have to use this flag if you want to
1430           intermix directives of different modules which contain
1431           URL-to-filename translators</strong>. The typical example
1432           is the use of <code>mod_alias</code> and
1433           <code>mod_rewrite</code>..</p>
1434
1435 <blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>For Apache hackers</strong></p>
1436                If the current Apache API had a filename-to-filename
1437               hook additionally to the URI-to-filename hook then we
1438               wouldn't need this flag! But without such a hook this
1439               flag is the only solution. The Apache Group has
1440               discussed this problem and will add such a hook in
1441               Apache version 2.0.
1442 </td></tr></table></blockquote>
1443         </li>
1444
1445         <li>'<strong><code>skip|S</code></strong>=<em>num</em>'
1446         (<strong>s</strong>kip next rule(s))<br>
1447          This flag forces the rewriting engine to skip the next
1448         <em>num</em> rules in sequence when the current rule
1449         matches. Use this to make pseudo if-then-else constructs:
1450         The last rule of the then-clause becomes
1451         <code>skip=N</code> where N is the number of rules in the
1452         else-clause. (This is <strong>not</strong> the same as the
1453         'chain|C' flag!)</li>
1454
1455         <li>
1456         '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>'
1457         (set <strong>e</strong>nvironment variable)<br>
1458          This forces an environment variable named <em>VAR</em> to
1459         be set to the value <em>VAL</em>, where <em>VAL</em> can
1460         contain regexp backreferences <code>$N</code> and
1461         <code>%N</code> which will be expanded. You can use this
1462         flag more than once to set more than one variable. The
1463         variables can be later dereferenced in many situations, but
1464         usually from within XSSI (via <code>&lt;!--#echo
1465         var="VAR"--&gt;</code>) or CGI (<em>e.g.</em>
1466         <code>$ENV{'VAR'}</code>). Additionally you can dereference
1467         it in a following RewriteCond pattern via
1468         <code>%{ENV:VAR}</code>. Use this to strip but remember
1469         information from URLs.</li>
1470       </ul>
1471
1472 <blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>Note</strong></p> Never forget that <em>Pattern</em> is
1473 applied to a complete URL in per-server configuration
1474 files. <strong>But in per-directory configuration files, the
1475 per-directory prefix (which always is the same for a specific
1476 directory!) is automatically <em>removed</em> for the pattern matching
1477 and automatically <em>added</em> after the substitution has been
1478 done.</strong> This feature is essential for many sorts of rewriting,
1479 because without this prefix stripping you have to match the parent
1480 directory which is not always possible.
1481
1482             <p>There is one exception: If a substitution string
1483             starts with ``<code>http://</code>'' then the directory
1484             prefix will <strong>not</strong> be added and an
1485             external redirect or proxy throughput (if flag
1486             <strong>P</strong> is used!) is forced!</p>
1487 </td></tr></table></blockquote>
1488
1489 <blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>Note</strong></p>
1490  To enable the rewriting engine
1491           for per-directory configuration files you need to set
1492           ``<code>RewriteEngine On</code>'' in these files
1493           <strong>and</strong> ``<code>Options
1494           FollowSymLinks</code>'' must be enabled. If your
1495           administrator has disabled override of
1496           <code>FollowSymLinks</code> for a user's directory, then
1497           you cannot use the rewriting engine. This restriction is
1498           needed for security reasons.
1499 </td></tr></table></blockquote>
1500
1501       <p>Here are all possible substitution combinations and their
1502       meanings:</p>
1503
1504       <p><strong>Inside per-server configuration
1505       (<code>httpd.conf</code>)<br>
1506        for request ``<code>GET
1507       /somepath/pathinfo</code>'':</strong><br>
1508       </p>
1509
1510       <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5">
1511         <tr>
1512           <td>
1513 <pre>
1514 <strong>Given Rule</strong>                                      <strong>Resulting Substitution</strong>
1515 ----------------------------------------------  ----------------------------------
1516 ^/somepath(.*) otherpath$1                      not supported, because invalid!
1517
1518 ^/somepath(.*) otherpath$1  [R]                 not supported, because invalid!
1519
1520 ^/somepath(.*) otherpath$1  [P]                 not supported, because invalid!
1521 ----------------------------------------------  ----------------------------------
1522 ^/somepath(.*) /otherpath$1                     /otherpath/pathinfo
1523
1524 ^/somepath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
1525                                                 via external redirection
1526
1527 ^/somepath(.*) /otherpath$1 [P]                 not supported, because silly!
1528 ----------------------------------------------  ----------------------------------
1529 ^/somepath(.*) http://thishost/otherpath$1      /otherpath/pathinfo
1530
1531 ^/somepath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
1532                                                 via external redirection
1533
1534 ^/somepath(.*) http://thishost/otherpath$1 [P]  not supported, because silly!
1535 ----------------------------------------------  ----------------------------------
1536 ^/somepath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
1537                                                 via external redirection
1538
1539 ^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
1540                                                 via external redirection
1541                                                 (the [R] flag is redundant)
1542
1543 ^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
1544                                                 via internal proxy
1545 </pre>
1546           </td>
1547         </tr>
1548       </table>
1549
1550       <p><strong>Inside per-directory configuration for
1551       <code>/somepath</code><br>
1552        (<em>i.e.</em>, file <code>.htaccess</code> in dir
1553       <code>/physical/path/to/somepath</code> containing
1554       <code>RewriteBase /somepath</code>)<br>
1555        for request ``<code>GET
1556       /somepath/localpath/pathinfo</code>'':</strong><br>
1557      </p>
1558
1559       <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5">
1560         <tr>
1561           <td>
1562 <pre>
1563 <strong>Given Rule</strong>                                      <strong>Resulting Substitution</strong>
1564 ----------------------------------------------  ----------------------------------
1565 ^localpath(.*) otherpath$1                      /somepath/otherpath/pathinfo
1566
1567 ^localpath(.*) otherpath$1  [R]                 http://thishost/somepath/otherpath/pathinfo
1568                                                 via external redirection
1569
1570 ^localpath(.*) otherpath$1  [P]                 not supported, because silly!
1571 ----------------------------------------------  ----------------------------------
1572 ^localpath(.*) /otherpath$1                     /otherpath/pathinfo
1573
1574 ^localpath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
1575                                                 via external redirection
1576
1577 ^localpath(.*) /otherpath$1 [P]                 not supported, because silly!
1578 ----------------------------------------------  ----------------------------------
1579 ^localpath(.*) http://thishost/otherpath$1      /otherpath/pathinfo
1580
1581 ^localpath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
1582                                                 via external redirection
1583
1584 ^localpath(.*) http://thishost/otherpath$1 [P]  not supported, because silly!
1585 ----------------------------------------------  ----------------------------------
1586 ^localpath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
1587                                                 via external redirection
1588
1589 ^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
1590                                                 via external redirection
1591                                                 (the [R] flag is redundant)
1592
1593 ^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
1594                                                 via internal proxy
1595 </pre>
1596           </td>
1597         </tr>
1598       </table>
1599
1600       <p><strong>Example:</strong></p>
1601
1602       <p>We want to rewrite URLs of the form </p>
1603
1604         <blockquote>
1605           <code>/</code> <em>Language</em> <code>/~</code>
1606           <em>Realname</em> <code>/.../</code> <em>File</em>
1607         </blockquote>
1608
1609         <p>into </p>
1610
1611         <blockquote>
1612           <code>/u/</code> <em>Username</em> <code>/.../</code>
1613           <em>File</em> <code>.</code> <em>Language</em>
1614         </blockquote>
1615
1616         <p>We take the rewrite mapfile from above and save it under
1617         <code>/path/to/file/map.txt</code>. Then we only have to
1618         add the following lines to the Apache server configuration
1619         file:</p>
1620
1621 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
1622 <pre>
1623 RewriteLog   /path/to/file/rewrite.log
1624 RewriteMap   real-to-user               txt:/path/to/file/map.txt
1625 RewriteRule  ^/([^/]+)/~([^/]+)/(.*)$   /u/${real-to-user:$2|nobody}/$3.$1
1626 </pre>
1627    </code></td></tr></table></blockquote>
1628   <hr/></blockquote><h3 align="center">Apache HTTP Server Version 2.0</h3><a href="./"><img src="../images/index.gif" alt="Index"/></a><a href="../"><img src="../images/home.gif" alt="Home"/></a></body></html>