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

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