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

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