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