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