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> |
  25 <a href="../fr/mod/mod_rewrite.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
  26 </div>
  27 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides a rule-based rewriting engine to rewrite requested
  28 URLs on the fly</td></tr>
  29 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  30 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>rewrite_module</td></tr>
  31 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_rewrite.c</td></tr></table>
  32 <h3>Summary</h3>
  33
  34         <p>The <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> module uses a rule-based rewriting
  35       engine, based on a regular-expression parser, to rewrite requested URLs on
  36       the fly. By default, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> maps a URL to a filesystem
  37       path. However, it can also be used to redirect one URL to another URL, or
  38       to invoke an internal proxy fetch.</p>
  39       <p><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> provides a flexible and powerful way to
  40       manipulate URLs using an unlimited number of rules. Each rule can have an
  41       unlimited number of attached rule conditions, to allow you to rewrite URL
  42       based on server variables, environment variables, HTTP headers, or time
  43       stamps.</p>
  44       <p><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> operates on the full URL path, including the
  45       path-info section. A rewrite rule can be invoked in
  46       <code>httpd.conf</code> or in <code>.htaccess</code>. The path generated
  47       by a rewrite rule can include a query string, or can lead to internal
  48       sub-processing, external request redirection, or internal proxy
  49       throughput.</p>
  50
  51       <p>Further details, discussion, and examples, are provided in the
  52       <a href="../rewrite/">detailed mod_rewrite documentation</a>.</p>
  53 </div>
  54 <div id="quickview"><h3 class="directives">Directives</h3>
  55 <ul id="toc">
  56 <li><img alt="" src="../images/down.gif" /> <a href="#rewritebase">RewriteBase</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">RewriteCond</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#rewriteengine">RewriteEngine</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#rewritemap">RewriteMap</a></li>
  60 <li><img alt="" src="../images/down.gif" /> <a href="#rewriteoptions">RewriteOptions</a></li>
  61 <li><img alt="" src="../images/down.gif" /> <a href="#rewriterule">RewriteRule</a></li>
  62 </ul>
  63 <h3>Topics</h3>
  64 <ul id="topics">
  65 <li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging</a></li>
  66 </ul></div>
  67 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  68 <div class="section">
  69 <h2><a name="logging" id="logging">Logging</a></h2>
  70
  71     <p><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> offers detailed logging of its actions
  72     at the <code>trace1</code> to <code>trace8</code> log levels. The
  73     log level can be set specifically for <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
  74     using the <code class="directive"><a href="../mod/core.html#loglevel">LogLevel</a></code> directive: Up to
  75     level <code>debug</code>, no actions are logged, while <code>trace8</code>
  76     means that practically all actions are logged.</p>
  77
  78     <div class="note">
  79       Using a high trace log level for <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
  80       will slow down your Apache HTTP Server dramatically! Use a log
  81       level higher than <code>trace2</code> only for debugging!
  82     </div>
  83
  84     <div class="example"><h3>Example</h3><p><code>
  85       LogLevel rewrite:trace3
  86     </code></p></div>
  87
  88     <div class="note"><h3>RewriteLog</h3>
  89       <p>Those familiar with earlier versions of
  90       <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> will no doubt be looking for the
  91       <code>RewriteLog</code> and <code>RewriteLogLevel</code>
  92       directives. This functionality has been completely replaced by the
  93       new per-module logging configuration mentioned above.
  94       </p>
  95
  96       <p>To get just the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>-specific log
  97       messages, pipe the log file through grep:</p>
  98     <div class="example"><p><code>
  99     tail -f error_log|fgrep '[rewrite:'
 100     </code></p></div>
 101     </div>
 102
 103 </div>
 104 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 105 <div class="directive-section"><h2><a name="RewriteBase" id="RewriteBase">RewriteBase</a> <a name="rewritebase" id="rewritebase">Directive</a></h2>
 106 <table class="directive">
 107 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the base URL for per-directory rewrites</td></tr>
 108 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteBase <em>URL-path</em></code></td></tr>
 109 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>None</code></td></tr>
 110 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 111 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 112 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 113 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 114 </table>
 115       <p>The <code class="directive">RewriteBase</code> directive explicitly
 116       sets the base URL-path (not filesystem directory path!)  for per-directory rewrites.
 117       When you use a <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
 118       in a <code>.htaccess</code> file, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> strips off
 119       the local directory prefix before processing, then rewrites the rest of
 120       the URL. When the rewrite is completed, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
 121       automatically adds the local directory prefix back on to the path.</p>
 122
 123       <p>This directive is <em>required</em> for per-directory rewrites whose context
 124       is a directory made available via the <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>
 125       directive.</p>
 126
 127       <p>If your URL path does not exist verbatim on the filesystem,
 128       or isn't directly under your <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>,
 129       you must use <code class="directive">RewriteBase</code> in every
 130       <code>.htaccess</code> file where you want to use <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives.</p>
 131
 132       <p>The example below demonstrates how to map
 133       http://example.com/myapp/index.html to
 134       /home/www/example/newsite.html, in a <code>.htaccess</code> file. This
 135       assumes that the content available at
 136       http://example.com/ is on disk at /home/www/example/</p>
 137 <div class="example"><pre>
 138 RewriteEngine On
 139 # The URL-path used to get to this context, not the filesystem path
 140 RewriteBase /myapp/
 141 RewriteRule ^index\.html$  newsite.html
 142 </pre></div>
 143
 144
 145 </div>
 146 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 147 <div class="directive-section"><h2><a name="RewriteCond" id="RewriteCond">RewriteCond</a> <a name="rewritecond" id="rewritecond">Directive</a></h2>
 148 <table class="directive">
 149 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a condition under which rewriting will take place
 150 </td></tr>
 151 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> RewriteCond
 152       <em>TestString</em> <em>CondPattern</em></code></td></tr>
 153 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 154 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 155 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 156 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 157 </table>
 158       <p>The <code class="directive">RewriteCond</code> directive defines a
 159       rule condition. One or more <code class="directive">RewriteCond</code>
 160       can precede a <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
 161       directive. The following rule is then only used if both
 162       the current state of the URI matches its pattern, <strong>and</strong> if these conditions are met.</p>
 163
 164       <p><em>TestString</em> is a string which can contain the
 165       following expanded constructs in addition to plain text:</p>
 166
 167       <ul>
 168         <li>
 169           <strong>RewriteRule backreferences</strong>: These are
 170           backreferences of the form <strong><code>$N</code></strong>
 171           (0 &lt;= N &lt;= 9). $1 to $9 provide access to the grouped
 172           parts (in parentheses) of the pattern, from the
 173           <code>RewriteRule</code> which is subject to the current
 174           set of <code>RewriteCond</code> conditions. $0 provides
 175           access to the whole string matched by that pattern.
 176         </li>
 177         <li>
 178           <strong>RewriteCond backreferences</strong>: These are
 179           backreferences of the form <strong><code>%N</code></strong>
 180           (0 &lt;= N &lt;= 9). %1 to %9 provide access to the grouped
 181           parts (again, in parentheses) of the pattern, from the last matched
 182           <code>RewriteCond</code> in the current set
 183           of conditions. %0 provides access to the whole string matched by
 184           that pattern.
 185         </li>
 186         <li>
 187           <strong>RewriteMap expansions</strong>: These are
 188           expansions of the form <strong><code>${mapname:key|default}</code></strong>.
 189           See <a href="#mapfunc">the documentation for
 190           RewriteMap</a> for more details.
 191         </li>
 192         <li>
 193           <strong>Server-Variables</strong>: These are variables of
 194           the form
 195             <strong><code>%{</code> <em>NAME_OF_VARIABLE</em>
 196             <code>}</code></strong>
 197           where <em>NAME_OF_VARIABLE</em> can be a string taken
 198           from the following list:
 199
 200           <table>
 201
 202             <tr>
 203               <th>HTTP headers:</th> <th>connection &amp; request:</th> <th />
 204             </tr>
 205
 206             <tr>
 207               <td>
 208                  HTTP_USER_AGENT<br />
 209                  HTTP_REFERER<br />
 210                  HTTP_COOKIE<br />
 211                  HTTP_FORWARDED<br />
 212                  HTTP_HOST<br />
 213                  HTTP_PROXY_CONNECTION<br />
 214                  HTTP_ACCEPT<br />
 215               </td>
 216
 217               <td>
 218                  REMOTE_ADDR<br />
 219                  REMOTE_HOST<br />
 220                  REMOTE_PORT<br />
 221                  REMOTE_USER<br />
 222                  REMOTE_IDENT<br />
 223                  REQUEST_METHOD<br />
 224                  SCRIPT_FILENAME<br />
 225                  PATH_INFO<br />
 226                  QUERY_STRING<br />
 227                  AUTH_TYPE<br />
 228               </td>
 229
 230               <td />
 231             </tr>
 232
 233             <tr>
 234               <th>server internals:</th> <th>date and time:</th> <th>specials:</th>
 235             </tr>
 236
 237             <tr>
 238               <td>
 239                  DOCUMENT_ROOT<br />
 240                  SERVER_ADMIN<br />
 241                  SERVER_NAME<br />
 242                  SERVER_ADDR<br />
 243                  SERVER_PORT<br />
 244                  SERVER_PROTOCOL<br />
 245                  SERVER_SOFTWARE<br />
 246               </td>
 247
 248               <td>
 249                  TIME_YEAR<br />
 250                  TIME_MON<br />
 251                  TIME_DAY<br />
 252                  TIME_HOUR<br />
 253                  TIME_MIN<br />
 254                  TIME_SEC<br />
 255                  TIME_WDAY<br />
 256                  TIME<br />
 257               </td>
 258
 259               <td>
 260                  API_VERSION<br />
 261                  THE_REQUEST<br />
 262                  REQUEST_URI<br />
 263                  REQUEST_FILENAME<br />
 264                  IS_SUBREQ<br />
 265                  HTTPS<br />
 266               </td>
 267             </tr>
 268           </table>
 269
 270                 <p>These variables all
 271                 correspond to the similarly named HTTP
 272                 MIME-headers, C variables of the Apache HTTP Server or
 273                 <code>struct tm</code> fields of the Unix system.
 274                 Most are documented elsewhere in the Manual or in
 275                 the CGI specification. Those that are special to
 276                 mod_rewrite include those below.</p>
 277         <div class="note">
 278                 <dl>
 279                   <dt><code>IS_SUBREQ</code></dt>
 280
 281                   <dd>Will contain the text "true" if the request
 282                   currently being processed is a sub-request,
 283                   "false" otherwise. Sub-requests may be generated
 284                   by modules that need to resolve additional files
 285                   or URIs in order to complete their tasks.</dd>
 286
 287                   <dt><code>API_VERSION</code></dt>
 288
 289                   <dd>This is the version of the Apache httpd module API
 290                   (the internal interface between server and
 291                   module) in the current httpd build, as defined in
 292                   include/ap_mmn.h. The module API version
 293                   corresponds to the version of Apache httpd in use (in
 294                   the release version of Apache httpd 1.3.14, for
 295                   instance, it is 19990320:10), but is mainly of
 296                   interest to module authors.</dd>
 297
 298                   <dt><code>THE_REQUEST</code></dt>
 299
 300                   <dd>The full HTTP request line sent by the
 301                   browser to the server (e.g., "<code>GET
 302                   /index.html HTTP/1.1</code>"). This does not
 303                   include any additional headers sent by the
 304                   browser.</dd>
 305
 306                   <dt><code>REQUEST_URI</code></dt>
 307
 308                   <dd>The resource requested in the HTTP request
 309                   line. (In the example above, this would be
 310                   "/index.html".)</dd>
 311
 312                   <dt><code>REQUEST_FILENAME</code></dt>
 313
 314                   <dd>The full local filesystem path to the file or
 315                   script matching the request, if this has already
 316                   been determined by the server at the time
 317                   <code>REQUEST_FILENAME</code> is referenced. Otherwise,
 318                   such as when used in virtual host context, the same
 319                   value as <code>REQUEST_URI</code>.</dd>
 320
 321                   <dt><code>HTTPS</code></dt>
 322
 323                   <dd>Will contain the text "on" if the connection is
 324                   using SSL/TLS, or "off" otherwise.  (This variable
 325                   can be safely used regardless of whether or not
 326                   <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is loaded).</dd>
 327
 328                 </dl>
 329 </div>
 330         </li>
 331       </ul>
 332
 333       <p>Other things you should be aware of:</p>
 334
 335       <ol>
 336         <li>
 337         <p>The variables SCRIPT_FILENAME and REQUEST_FILENAME
 338         contain the same value - the value of the
 339         <code>filename</code> field of the internal
 340         <code>request_rec</code> structure of the Apache HTTP Server.
 341         The first name is the commonly known CGI variable name
 342         while the second is the appropriate counterpart of
 343         REQUEST_URI (which contains the value of the
 344         <code>uri</code> field of <code>request_rec</code>).</p>
 345         <p>If a substitution occurred and the rewriting continues,
 346         the value of both variables will be updated accordingly.</p>
 347         <p>If used in per-server context (<em>i.e.</em>, before the
 348         request is mapped to the filesystem) SCRIPT_FILENAME and
 349         REQUEST_FILENAME cannot contain the full local filesystem
 350         path since the path is unknown at this stage of processing.
 351         Both variables will initially contain the value of REQUEST_URI
 352         in that case. In order to obtain the full local filesystem
 353         path of the request in per-server context, use an URL-based
 354         look-ahead <code>%{LA-U:REQUEST_FILENAME}</code> to determine
 355         the final value of REQUEST_FILENAME.</p></li>
 356
 357         <li>
 358         <code>%{ENV:variable}</code>, where <em>variable</em> can be
 359         any environment variable, is also available.
 360         This is looked-up via internal
 361         Apache httpd structures and (if not found there) via
 362         <code>getenv()</code> from the Apache httpd server process.</li>
 363
 364         <li>
 365         <code>%{SSL:variable}</code>, where <em>variable</em> is the
 366         name of an <a href="mod_ssl.html#envvars">SSL environment
 367         variable</a>, can be used whether or not
 368         <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is loaded, but will always expand to
 369         the empty string if it is not.  Example:
 370         <code>%{SSL:SSL_CIPHER_USEKEYSIZE}</code> may expand to
 371         <code>128</code>.</li>
 372
 373         <li>
 374         <code>%{HTTP:header}</code>, where <em>header</em> can be
 375         any HTTP MIME-header name, can always be used to obtain the
 376         value of a header sent in the HTTP request.
 377         Example: <code>%{HTTP:Proxy-Connection}</code> is
 378         the value of the HTTP header
 379         ``<code>Proxy-Connection:</code>''.
 380         <p>If a HTTP header is used in a condition this header is added to
 381         the Vary header of the response in case the condition evaluates to
 382         to true for the request. It is <strong>not</strong> added if the
 383         condition evaluates to false for the request. Adding the HTTP header
 384         to the Vary header of the response is needed for proper caching.</p>
 385         <p>It has to be kept in mind that conditions follow a short circuit
 386         logic in the case of the '<strong><code>ornext|OR</code></strong>' flag
 387         so that certain conditions might not be evaluated at all.</p></li>
 388
 389         <li>
 390         <code>%{LA-U:variable}</code> can be used for look-aheads which perform
 391         an internal (URL-based) sub-request to determine the final
 392         value of <em>variable</em>. This can be used to access
 393         variable for rewriting which is not available at the current
 394         stage, but will be set in a later phase.
 395         <p>For instance, to rewrite according to the
 396         <code>REMOTE_USER</code> variable from within the
 397         per-server context (<code>httpd.conf</code> file) you must
 398         use <code>%{LA-U:REMOTE_USER}</code> - this
 399         variable is set by the authorization phases, which come
 400         <em>after</em> the URL translation phase (during which mod_rewrite
 401         operates).</p>
 402         <p>On the other hand, because mod_rewrite implements
 403         its per-directory context (<code>.htaccess</code> file) via
 404         the Fixup phase of the API and because the authorization
 405         phases come <em>before</em> this phase, you just can use
 406         <code>%{REMOTE_USER}</code> in that context.</p></li>
 407
 408         <li>
 409         <code>%{LA-F:variable}</code> can be used to perform an internal
 410         (filename-based) sub-request, to determine the final value
 411         of <em>variable</em>. Most of the time, this is the same as
 412         LA-U above.</li>
 413       </ol>
 414
 415       <p><em>CondPattern</em> is the condition pattern,
 416        a regular expression which is applied to the
 417       current instance of the <em>TestString</em>.
 418       <em>TestString</em> is first evaluated, before being matched against
 419       <em>CondPattern</em>.</p>
 420
 421       <p><em>CondPattern</em> is usually a
 422       <em>perl compatible regular expression</em>, but there is
 423       additional syntax available to perform other useful tests against
 424       the <em>Teststring</em>:</p>
 425
 426       <ol>
 427         <li>You can prefix the pattern string with a
 428         '<code>!</code>' character (exclamation mark) to specify a
 429         <strong>non</strong>-matching pattern.</li>
 430
 431         <li>
 432           You can perform lexicographical string comparisons:
 433
 434           <ul>
 435             <li>'<strong>&lt;CondPattern</strong>' (lexicographically
 436             precedes)<br />
 437             Treats the <em>CondPattern</em> as a plain string and
 438             compares it lexicographically to <em>TestString</em>. True if
 439             <em>TestString</em> lexicographically precedes
 440             <em>CondPattern</em>.</li>
 441
 442             <li>'<strong>&gt;CondPattern</strong>' (lexicographically
 443             follows)<br />
 444             Treats the <em>CondPattern</em> as a plain string and
 445             compares it lexicographically to <em>TestString</em>. True if
 446             <em>TestString</em> lexicographically follows
 447             <em>CondPattern</em>.</li>
 448
 449             <li>'<strong>=CondPattern</strong>' (lexicographically
 450             equal)<br />
 451             Treats the <em>CondPattern</em> as a plain string and
 452             compares it lexicographically to <em>TestString</em>. True if
 453             <em>TestString</em> is lexicographically equal to
 454             <em>CondPattern</em> (the two strings are exactly
 455             equal, character for character). If <em>CondPattern</em>
 456             is <code>""</code> (two quotation marks) this
 457             compares <em>TestString</em> to the empty string.</li>
 458
 459             <li>'<strong>&lt;=CondPattern</strong>' (lexicographically
 460             less than or equal to)<br />
 461             Treats the <em>CondPattern</em> as a plain string and
 462             compares it lexicographically to <em>TestString</em>. True
 463             if <em>TestString</em> lexicographically precedes
 464             <em>CondPattern</em>, or is equal to <em>CondPattern</em>
 465             (the two strings are equal, character for character).</li>
 466
 467             <li>'<strong>&gt;=CondPattern</strong>' (lexicographically
 468             greater than or equal to)<br />
 469             Treats the <em>CondPattern</em> as a plain string and
 470             compares it lexicographically to <em>TestString</em>. True
 471             if <em>TestString</em> lexicographically follows
 472             <em>CondPattern</em>, or is equal to <em>CondPattern</em>
 473             (the two strings are equal, character for character).</li>
 474         </ul></li>
 475
 476         <li>
 477           You can perform integer comparisons:
 478           <ul>
 479
 480             <li>'<strong>-eq</strong>' (is numerically
 481             <strong>eq</strong>ual to)<br />
 482             The <em>TestString</em> is treated as an integer, and is
 483             numerically compared to the <em>CondPattern</em>. True if
 484             the two are numerically equal.</li>
 485
 486             <li>'<strong>-ge</strong>' (is numerically
 487             <strong>g</strong>reater than or <strong>e</strong>qual to)<br />
 488             The <em>TestString</em> is treated as an integer, and is
 489             numerically compared to the <em>CondPattern</em>. True if
 490             the <em>TestString</em> is numerically greater than or equal
 491             to the <em>CondPattern</em>.</li>
 492
 493              <li>'<strong>-gt</strong>' (is numerically
 494             <strong>g</strong>reater <strong>t</strong>han)<br />
 495             The <em>TestString</em> is treated as an integer, and is
 496             numerically compared to the <em>CondPattern</em>. True if
 497             the <em>TestString</em> is numerically greater than
 498             the <em>CondPattern</em>.</li>
 499
 500             <li>'<strong>-le</strong>' (is numerically
 501             <strong>l</strong>ess than or <strong>e</strong>qual to)<br />
 502             The <em>TestString</em> is treated as an integer, and is
 503             numerically compared to the <em>CondPattern</em>. True if
 504             the <em>TestString</em> is numerically less than or equal
 505             to the <em>CondPattern</em>. Avoid confusion with the
 506             <strong>-l</strong> by using the <strong>-L</strong> or
 507             <strong>-h</strong> variant.</li>
 508
 509              <li>'<strong>-lt</strong>' (is numerically
 510             <strong>l</strong>ess <strong>t</strong>han)<br />
 511             The <em>TestString</em> is treated as an integer, and is
 512             numerically compared to the <em>CondPattern</em>. True if
 513             the <em>TestString</em> is numerically less than
 514             the <em>CondPattern</em>. Avoid confusion with the
 515             <strong>-l</strong> by using the <strong>-L</strong> or
 516             <strong>-h</strong> variant.</li>
 517
 518            </ul>
 519         </li>
 520
 521         <li>You can perform various file attribute tests:
 522           <ul>
 523             <li>'<strong>-d</strong>' (is
 524             <strong>d</strong>irectory)<br />
 525              Treats the <em>TestString</em> as a pathname and tests
 526             whether or not it exists, and is a directory.</li>
 527
 528             <li>'<strong>-f</strong>' (is regular
 529             <strong>f</strong>ile)<br />
 530              Treats the <em>TestString</em> as a pathname and tests
 531             whether or not it exists, and is a regular file.</li>
 532
 533             <li>'<strong>-F</strong>' (is existing file, via
 534             subrequest)<br />
 535             Checks whether or not <em>TestString</em> is a valid file,
 536             accessible via all the server's currently-configured
 537             access controls for that path. This uses an internal
 538             subrequest to do the check, so use it with care -
 539             it can impact your server's performance!</li>
 540
 541             <li>'<strong>-H</strong>' (is symbolic link, bash convention)<br />
 542             See <strong>-l</strong>.</li>
 543
 544             <li>'<strong>-l</strong>' (is symbolic
 545             <strong>l</strong>ink)<br />
 546             Treats the <em>TestString</em> as a pathname and tests
 547             whether or not it exists, and is a symbolic link. May also
 548             use the bash convention of <strong>-L</strong> or
 549             <strong>-h</strong> if there's a possibility of confusion
 550             such as when using the <strong>-lt</strong> or
 551             <strong>-le</strong> tests.</li>
 552
 553             <li>'<strong>-L</strong>' (is symbolic link, bash convention)<br />
 554             See <strong>-l</strong>.</li>
 555
 556             <li>'<strong>-s</strong>' (is regular file, with
 557             <strong>s</strong>ize)<br />
 558             Treats the <em>TestString</em> as a pathname and tests
 559             whether or not it exists, and is a regular file with size greater
 560             than zero.</li>
 561
 562             <li>'<strong>-U</strong>' (is existing URL, via
 563             subrequest)<br />
 564             Checks whether or not <em>TestString</em> is a valid URL,
 565             accessible via all the server's currently-configured
 566             access controls for that path. This uses an internal
 567             subrequest to do the check, so use it with care -
 568             it can impact your server's performance!</li>
 569
 570             <li>'<strong>-x</strong>' (has e<strong>x</strong>ecutable
 571             permissions)<br />
 572             Treats the <em>TestString</em> as a pathname and tests
 573             whether or not it exists, and has executable permissions.
 574             These permissions are determined according to
 575             the underlying OS.</li>
 576
 577           </ul>
 578
 579 <div class="note"><h3>Note:</h3>
 580               All of these tests can
 581               also be prefixed by an exclamation mark ('!') to
 582               negate their meaning.
 583 </div>
 584         </li>
 585
 586         <li>You can also set special flags for
 587       <em>CondPattern</em> by appending
 588         <strong><code>[</code><em>flags</em><code>]</code></strong>
 589       as the third argument to the <code>RewriteCond</code>
 590       directive, where <em>flags</em> is a comma-separated list of any of the
 591       following flags:
 592
 593       <ul>
 594         <li>'<strong><code>nocase|NC</code></strong>'
 595         (<strong>n</strong>o <strong>c</strong>ase)<br />
 596         This makes the test case-insensitive - differences
 597         between 'A-Z' and 'a-z' are ignored, both in the
 598         expanded <em>TestString</em> and the <em>CondPattern</em>.
 599         This flag is effective only for comparisons between
 600         <em>TestString</em> and <em>CondPattern</em>. It has no
 601         effect on filesystem and subrequest checks.</li>
 602
 603         <li>
 604           '<strong><code>ornext|OR</code></strong>'
 605           (<strong>or</strong> next condition)<br />
 606           Use this to combine rule conditions with a local OR
 607           instead of the implicit AND. Typical example:
 608
 609 <div class="example"><pre>
 610 RewriteCond %{REMOTE_HOST}  ^host1  [OR]
 611 RewriteCond %{REMOTE_HOST}  ^host2  [OR]
 612 RewriteCond %{REMOTE_HOST}  ^host3
 613 RewriteRule ...some special stuff for any of these hosts...
 614 </pre></div>
 615
 616           Without this flag you would have to write the condition/rule
 617           pair three times.
 618         </li>
 619
 620         <li>'<strong><code>novary|NV</code></strong>'
 621         (<strong>n</strong>o <strong>v</strong>ary)<br />
 622         If a HTTP header is used in the condition, this flag prevents
 623         this header from being added to the Vary header of the response. <br />
 624         Using this flag might break proper caching of the response if
 625         the representation of this response varies on the value of this header.
 626         So this flag should be only used if the meaning of the Vary header
 627         is well understood.
 628         </li>
 629       </ul>
 630       </li>
 631      </ol>
 632
 633       <p><strong>Example:</strong></p>
 634
 635        <p>To rewrite the Homepage of a site according to the
 636         ``<code>User-Agent:</code>'' header of the request, you can
 637         use the following: </p>
 638
 639 <div class="example"><pre>
 640 RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla
 641 RewriteRule  ^/$                 /homepage.max.html  [L]
 642
 643 RewriteCond  %{HTTP_USER_AGENT}  ^Lynx
 644 RewriteRule  ^/$                 /homepage.min.html  [L]
 645
 646 RewriteRule  ^/$                 /homepage.std.html  [L]
 647 </pre></div>
 648
 649         <p>Explanation: If you use a browser which identifies itself
 650         as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you
 651         get the max homepage (which could include frames, or other special
 652         features).
 653         If you use the Lynx browser (which is terminal-based), then
 654         you get the min homepage (which could be a version designed for
 655         easy, text-only browsing).
 656         If neither of these conditions apply (you use any other browser,
 657         or your browser identifies itself as something non-standard), you get
 658         the std (standard) homepage.</p>
 659
 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="RewriteEngine" id="RewriteEngine">RewriteEngine</a> <a name="rewriteengine" id="rewriteengine">Directive</a></h2>
 664 <table class="directive">
 665 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables or disables runtime rewriting engine</td></tr>
 666 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteEngine on|off</code></td></tr>
 667 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteEngine off</code></td></tr>
 668 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 669 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 670 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 671 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 672 </table>
 673
 674       <p>The <code class="directive">RewriteEngine</code> directive enables or
 675       disables the runtime rewriting engine. If it is set to
 676       <code>off</code> this module does no runtime processing at
 677       all. It does not even update the <code>SCRIPT_URx</code>
 678       environment variables.</p>
 679
 680       <p>Use this directive to disable the module instead of
 681       commenting out all the <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives!</p>
 682
 683       <p>Note that rewrite configurations are not
 684       inherited by virtual hosts. This means that you need to have a
 685       <code>RewriteEngine on</code> directive for each virtual host
 686       in which you wish to use rewrite rules.</p>
 687
 688       <p><code class="directive">RewriteMap</code> directives of the type <code>prg</code>
 689       are not started during server initialization if they're defined in a
 690       context that does not have <code class="directive">RewriteEngine</code>  set to
 691       <code>on</code></p>
 692
 693 </div>
 694 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 695 <div class="directive-section"><h2><a name="RewriteMap" id="RewriteMap">RewriteMap</a> <a name="rewritemap" id="rewritemap">Directive</a></h2>
 696 <table class="directive">
 697 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a mapping function for key-lookup</td></tr>
 698 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
 699 </code></td></tr>
 700 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 701 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 702 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 703 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The choice of different dbm types is available in
 704 Apache HTTP Server 2.0.41 and later</td></tr>
 705 </table>
 706       <p>The <code class="directive">RewriteMap</code> directive defines a
 707       <em>Rewriting Map</em> which can be used inside rule
 708       substitution strings by the mapping-functions to
 709       insert/substitute fields through a key lookup. The source of
 710       this lookup can be of various types.</p>
 711
 712       <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
 713       the name of the map and will be used to specify a
 714       mapping-function for the substitution strings of a rewriting
 715       rule via one of the following constructs:</p>
 716
 717       <p class="indent">
 718         <strong><code>${</code> <em>MapName</em> <code>:</code>
 719         <em>LookupKey</em> <code>}</code><br />
 720          <code>${</code> <em>MapName</em> <code>:</code>
 721         <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
 722         <code>}</code></strong>
 723       </p>
 724
 725       <p>When such a construct occurs, the map <em>MapName</em> is
 726       consulted and the key <em>LookupKey</em> is looked-up. If the
 727       key is found, the map-function construct is substituted by
 728       <em>SubstValue</em>. If the key is not found then it is
 729       substituted by <em>DefaultValue</em> or by the empty string
 730       if no <em>DefaultValue</em> was specified.</p>
 731
 732       <p>For example, you might define a
 733       <code class="directive">RewriteMap</code> as:</p>
 734
 735       <div class="example"><p><code>
 736       RewriteMap examplemap txt:/path/to/file/map.txt
 737       </code></p></div>
 738
 739       <p>You would then be able to use this map in a
 740       <code class="directive">RewriteRule</code> as follows:</p>
 741
 742       <div class="example"><p><code>
 743       RewriteRule ^/ex/(.*) ${examplemap:$1}
 744       </code></p></div>
 745
 746       <p>The following combinations for <em>MapType</em> and
 747       <em>MapSource</em> can be used:</p>
 748
 749     <dl>
 750
 751     <dt>txt</dt>
 752         <dd>A plain text file containing space-separated key-value
 753         pairs, one per line. (<a href="../rewrite/rewritemap.html#txt">Details ...</a>)</dd>
 754
 755     <dt>rnd</dt>
 756         <dd>Randomly selects an entry from a plain text file (<a href="../rewrite/rewritemap.html#rnd">Details ...</a>)</dd>
 757
 758     <dt>dbm</dt>
 759         <dd>Looks up an entry in a dbm file containing name, value
 760         pairs. Hash is constructed from a plain text file format using
 761         the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code>
 762         utility.  (<a href="../rewrite/rewritemap.html#dbm">Details ...</a>)</dd>
 763
 764     <dt>int</dt>
 765         <dd>One of the four available internal functions provided by
 766         <code>RewriteMap</code>: toupper, tolower, escape or
 767         unescape. (<a href="../rewrite/rewritemap.html#int">Details ...</a>)</dd>
 768
 769     <dt>prg</dt>
 770         <dd>Calls an external program or script to process the
 771         rewriting. (<a href="../rewrite/rewritemap.html#prg">Details ...</a>)</dd>
 772
 773     <dt>dbd or fastdbd</dt>
 774         <dd>A SQL SELECT statement to be performed to look up the
 775         rewrite target. (<a href="../rewrite/rewritemap.html#dbd">Details ...</a>)</dd>
 776     </dl>
 777
 778     <p>Further details, and numerous examples, may be found in the <a href="../rewrite/rewritemap.html">RewriteMap HowTo</a></p>
 779
 780
 781 </div>
 782 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 783 <div class="directive-section"><h2><a name="RewriteOptions" id="RewriteOptions">RewriteOptions</a> <a name="rewriteoptions" id="rewriteoptions">Directive</a></h2>
 784 <table class="directive">
 785 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets some special options for the rewrite engine</td></tr>
 786 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteOptions <var>Options</var></code></td></tr>
 787 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 788 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 789 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 790 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 791 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><code>MaxRedirects</code> is no longer available in version 2.1 and
 792 later</td></tr>
 793 </table>
 794
 795       <p>The <code class="directive">RewriteOptions</code> directive sets some
 796       special options for the current per-server or per-directory
 797       configuration. The <em>Option</em> string can currently
 798       only be one of the following:</p>
 799
 800       <dl>
 801       <dt><code>inherit</code></dt>
 802       <dd>This forces the current configuration to inherit the
 803       configuration of the parent. In per-virtual-server context,
 804       this means that the maps, conditions and rules of the main
 805       server are inherited. In per-directory context this means
 806       that conditions and rules of the parent directory's
 807       <code>.htaccess</code> configuration or
 808       <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code>
 809       sections are inherited. The inherited rules are virtually copied
 810       to the section where this directive is being used. If used in
 811       combination with local rules, the inherited rules are copied behind
 812       the local rules. The position of this directive - below or above
 813       of local rules - has no influence on this behavior. If local
 814       rules forced the rewriting to stop, the inherited rules won't
 815       be processed.</dd>
 816       </dl>
 817
 818 </div>
 819 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 820 <div class="directive-section"><h2><a name="RewriteRule" id="RewriteRule">RewriteRule</a> <a name="rewriterule" id="rewriterule">Directive</a></h2>
 821 <table class="directive">
 822 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines rules for the rewriting engine</td></tr>
 823 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteRule
 824       <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</code></td></tr>
 825 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 826 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 827 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 828 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 829 </table>
 830       <p>The <code class="directive">RewriteRule</code> directive is the real
 831       rewriting workhorse. The directive can occur more than once,
 832       with each instance defining a single rewrite rule. The
 833       order in which these rules are defined is important - this is the order
 834       in which they will be applied at run-time.</p>
 835
 836       <p><a id="patterns" name="patterns"><em>Pattern</em></a> is
 837       a perl compatible <a id="regexp" name="regexp">regular
 838       expression</a>. On the first RewriteRule it is applied to the (%-encoded)
 839       <a href="./directive-dict.html#Syntax">URL-path</a> of the request;
 840       subsequent patterns are applied to the output of the last matched
 841       RewriteRule.</p>
 842
 843 <div class="note"><h3>What is matched?</h3>
 844       <p>The <em>Pattern</em> will initially be matched against the part of the
 845       URL after the hostname and port, and before the query string.</p>
 846
 847       <p>When the RewriteRule appears in per-directory (htaccess) context, the
 848       <em>Pattern</em> is matched against what remains of the URL after removing
 849       the prefix that lead Apache httpd to the current rules (see the
 850       <code class="directive"><a href="#rewritebase">RewriteBase</a></code>).  The removed prefix
 851       always ends with a slash, meaning the matching occurs against a string which
 852       never has a leading slash.  A <em>Pattern</em> with <code>^/</code> never
 853       matches in per-directory context.</p>
 854
 855       <p>If you wish to match against the hostname, port, or query string, use a
 856       <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
 857       <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
 858       <code>%{QUERY_STRING}</code> variables respectively. If you wish to
 859       match against the full URL-path in a per-directory (htaccess) RewriteRule,
 860       use the <code>%{REQUEST_URI}</code> variable.</p>
 861
 862 </div>
 863
 864       <p>For some hints on <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
 865       expressions</a>, see
 866       the <a href="../rewrite/intro.html#regex">mod_rewrite
 867       Introduction</a>.</p>
 868
 869       <p>In mod_rewrite, the NOT character
 870       ('<code>!</code>') is also available as a possible pattern
 871       prefix. This enables you to negate a pattern; to say, for instance:
 872       ``<em>if the current URL does <strong>NOT</strong> match this
 873       pattern</em>''. This can be used for exceptional cases, where
 874       it is easier to match the negative pattern, or as a last
 875       default rule.</p>
 876
 877 <div class="note"><h3>Note</h3>
 878 When using the NOT character to negate a pattern, you cannot include
 879 grouped wildcard parts in that pattern. This is because, when the
 880 pattern does NOT match (ie, the negation matches), there are no
 881 contents for the groups. Thus, if negated patterns are used, you
 882 cannot use <code>$N</code> in the substitution string!
 883 </div>
 884
 885       <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
 886       rewrite rule is the string that replaces the original URL-path that
 887       was matched by <em>Pattern</em>.  The <em>Substitution</em> may
 888       be a:</p>
 889
 890       <dl>
 891
 892         <dt>file-system path</dt>
 893
 894         <dd>Designates the location on the file-system of the resource
 895         to be delivered to the client.</dd>
 896
 897         <dt>URL-path</dt>
 898
 899         <dd>A <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>-relative path to the
 900         resource to be served. Note that <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
 901         tries to guess whether you have specified a file-system path
 902         or a URL-path by checking to see if the first segment of the
 903         path exists at the root of the file-system. For example, if
 904         you specify a <em>Substitution</em> string of
 905         <code>/www/file.html</code>, then this will be treated as a
 906         URL-path <em>unless</em> a directory named <code>www</code>
 907         exists at the root or your file-system, in which case it will
 908         be treated as a file-system path. If you wish other
 909         URL-mapping directives (such as <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>) to be applied to the
 910         resulting URL-path, use the <code>[PT]</code> flag as
 911         described below.</dd>
 912
 913         <dt>Absolute URL</dt>
 914
 915         <dd>If an absolute URL is specified,
 916         <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> checks to see whether the
 917         hostname matches the current host. If it does, the scheme and
 918         hostname are stripped out and the resulting path is treated as
 919         a URL-path. Otherwise, an external redirect is performed for
 920         the given URL. To force an external redirect back to the
 921         current host, see the <code>[R]</code> flag below.</dd>
 922
 923         <dt><code>-</code> (dash)</dt>
 924
 925         <dd>A dash indicates that no substitution should be performed
 926         (the existing path is passed through untouched). This is used
 927         when a flag (see below) needs to be applied without changing
 928         the path.</dd>
 929
 930       </dl>
 931
 932       <p>In addition to plain text, the <em>Substition</em> string can include</p>
 933
 934       <ol>
 935         <li>back-references (<code>$N</code>) to the RewriteRule
 936         pattern</li>
 937
 938         <li>back-references (<code>%N</code>) to the last matched
 939         RewriteCond pattern</li>
 940
 941         <li>server-variables as in rule condition test-strings
 942         (<code>%{VARNAME}</code>)</li>
 943
 944         <li><a href="#mapfunc">mapping-function</a> calls
 945         (<code>${mapname:key|default}</code>)</li>
 946       </ol>
 947
 948       <p>Back-references are identifiers of the form
 949       <code>$</code><strong>N</strong>
 950       (<strong>N</strong>=0..9), which will be replaced
 951       by the contents of the <strong>N</strong>th group of the
 952       matched <em>Pattern</em>. The server-variables are the same
 953       as for the <em>TestString</em> of a <code>RewriteCond</code>
 954       directive. The mapping-functions come from the
 955       <code>RewriteMap</code> directive and are explained there.
 956       These three types of variables are expanded in the order above.</p>
 957
 958       <p>As already mentioned, all rewrite rules are
 959       applied to the <em>Substitution</em> (in the order in which
 960       they are defined
 961       in the config file). The URL is <strong>completely
 962       replaced</strong> by the <em>Substitution</em> and the
 963       rewriting process continues until all rules have been applied,
 964       or it is explicitly terminated by a
 965       <code><strong>L</strong></code> flag.</p>
 966
 967      <div class="note"><h3>Modifying the Query String</h3>
 968       <p>By default, the query string is passed through unchanged. You
 969       can, however, create URLs in the substitution string containing
 970       a query string part. Simply use a question mark inside the
 971       substitution string to indicate that the following text should
 972       be re-injected into the query string. When you want to erase an
 973       existing query string, end the substitution string with just a
 974       question mark. To combine new and old query strings, use the
 975       <code>[QSA]</code> flag.</p>
 976      </div>
 977
 978       <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">actions</a> to be performed by
 979       appending <strong><code>[</code><em>flags</em><code>]</code></strong>
 980       as the third argument to the <code>RewriteRule</code>
 981       directive. <em>Flags</em> is a comma-separated list, surround by square
 982       brackets, of any of the flags in the following table. More
 983       details, and examples, for each flag, are available in the <a href="../rewrite/flags.html">Rewrite Flags document</a>.</p>
 984
 985     <table class="bordered">
 986     <tr><th>Flag and syntax</th>
 987         <th>Function</th>
 988     </tr>
 989     <tr>
 990         <td>B</td>
 991         <td>Escape non-alphanumeric characters <em>before</em> applying
 992         the transformation. <em><a href="../rewrite/flags.html#flag_b">details ...</a></em></td>
 993     </tr>
 994     <tr>
 995         <td>chain|C</td>
 996         <td>Rule is chained to the following rule. If the rule fails,
 997         the rule(s) chained to it will be skipped. <em><a href="../rewrite/flags.html#flag_c">details ...</a></em></td>
 998     </tr>
 999     <tr>
1000         <td>cookie|CO=<em>NAME</em>:<em>VAL</em></td>
1001         <td>Sets a cookie in the client browser. Full syntax is:
1002         CO=<em>NAME</em>:<em>VAL</em>[:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>[:<em>secure</em>[:<em>httponly</em>]]]]] <em><a href="../rewrite/flags.html#flag_co">details ...</a></em>
1003         </td>
1004     </tr>
1005     <tr>
1006         <td>discardpathinfo|DPI</td>
1007         <td>Causes the PATH_INFO portion of the rewritten URI to be
1008         discarded. <em><a href="../rewrite/flags.html#flag_dpi">details
1009         ...</a></em></td>
1010     </tr>
1011     <tr>
1012         <td>env|E=<em>VAR</em>[:<em>VAL</em>]</td>
1013         <td>Causes an environment variable <em>VAR</em> to be set (to the
1014         value <em>VAL</em> if provided). <em><a href="../rewrite/flags.html#flag_e">details ...</a></em></td>
1015     </tr>
1016     <tr>
1017         <td>forbidden|F</td>
1018         <td>Returns a 403 FORBIDDEN response to the client browser.
1019         <em><a href="../rewrite/flags.html#flag_f">details ...</a></em></td>
1020     </tr>
1021     <tr>
1022         <td>gone|G</td>
1023         <td>Returns a 410 GONE response to the client browser. <em><a href="../rewrite/flags.html#flag_g">details ...</a></em></td>
1024     </tr>
1025     <tr>
1026         <td>Handler|H=<em>Content-handler</em></td>
1027         <td>Causes the resulting URI to be sent to the specified
1028         <em>Content-handler</em> for processing. <em><a href="../rewrite/flags.html#flag_h">details ...</a></em></td>
1029     </tr>
1030     <tr>
1031         <td>last|L</td>
1032         <td>Stop the rewriting process immediately and don't apply any
1033         more rules. Especially note caveats for per-directory and
1034         .htaccess context. <em><a href="../rewrite/flags.html#flag_l">details ...</a></em></td>
1035     </tr>
1036     <tr>
1037         <td>next|N</td>
1038         <td>Re-run the rewriting process, starting again with the first
1039         rule, using the result of the ruleset so far as a starting
1040         point. <em><a href="../rewrite/flags.html#flag_n">details
1041         ...</a></em></td>
1042     </tr>
1043     <tr>
1044         <td>nocase|NC</td>
1045         <td>Makes the pattern pattern comparison case-insensitive.
1046         <em><a href="../rewrite/flags.html#flag_nc">details ...</a></em></td>
1047     </tr>
1048     <tr>
1049         <td>noescape|NE</td>
1050         <td>Prevent mod_rewrite from applying hexcode escaping of
1051         special characters in the result of the rewrite. <em><a href="../rewrite/flags.html#flag_ne">details ...</a></em></td>
1052     </tr>
1053     <tr>
1054         <td>nosubreq|NS</td>
1055         <td>Causes a rule to be skipped if the current request is an
1056         internal sub-request. <em><a href="../rewrite/flags.html#flag_ns">details ...</a></em></td>
1057     </tr>
1058     <tr>
1059         <td>proxy|P</td>
1060         <td>Force the substitution URL to be internally sent as a proxy
1061         request. <em><a href="../rewrite/flags.html#flag_p">details
1062         ...</a></em></td>
1063     </tr>
1064     <tr>
1065         <td>passthrough|PT</td>
1066         <td>Forces the resulting URI to be passed back to the URL
1067         mapping engine for processing of other URI-to-filename
1068         translators, such as <code>Alias</code> or
1069         <code>Redirect</code>. <em><a href="../rewrite/flags.html#flag_pt">details ...</a></em></td>
1070     </tr>
1071     <tr>
1072         <td>qsappend|QSA</td>
1073         <td>Appends any query string created in the rewrite target to
1074         any query string that was in the original request URL. <em><a href="../rewrite/flags.html#flag_qsa">details ...</a></em></td>
1075     </tr>
1076     <tr>
1077         <td>qsdiscard|QSD</td>
1078         <td>Discard any query string attached to the incoming URI.
1079         <em><a href="../rewrite/flags.html#flag_qsd">details
1080         ...</a></em></td>
1081     </tr>
1082     <tr>
1083         <td>redirect|R[=<em>code</em>]</td>
1084         <td>Forces an external redirect, optionally with the specified
1085         HTTP status code. <em><a href="../rewrite/flags.html#flag_r">details ...</a></em>
1086         </td>
1087     </tr>
1088     <tr>
1089         <td>skip|S=<em>num</em></td>
1090         <td>Tells the rewriting engine to skip the next <em>num</em>
1091         rules if the current rule matches. <em><a href="../rewrite/flags.html#flag_s">details ...</a></em></td>
1092     </tr>
1093     <tr>
1094         <td>tyle|T=<em>MIME-type</em></td>
1095         <td>Force the <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> of the target file
1096         to be the specified type. <em><a href="../rewrite/flags.html#flag_t">details ...</a></em></td>
1097     </tr>
1098     </table>
1099
1100 <div class="note"><h3>Home directory expansion</h3>
1101 <p> When the substitution string begins with a string
1102 resembling "/~user" (via explicit text or backreferences), mod_rewrite performs
1103 home directory expansion independent of the presence or configuration
1104 of <code class="module"><a href="../mod/mod_userdir.html">mod_userdir</a></code>.</p>
1105
1106 <p> This expansion does not occur when the <em>PT</em>
1107 flag is used on the <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
1108 directive.</p>
1109 </div>
1110
1111 <div class="note"><h3>Per-directory Rewrites</h3>
1112
1113 <p>The rewrite engine may be used in <a href="../howto/htaccess.html">.htaccess</a> files.  To enable the
1114 rewrite engine for these files you need to set
1115 "<code>RewriteEngine On</code>" <strong>and</strong>
1116 "<code>Options FollowSymLinks</code>" must be enabled. If your
1117 administrator has disabled override of <code>FollowSymLinks</code> for
1118 a user's directory, then you cannot use the rewrite engine. This
1119 restriction is required for security reasons.</p>
1120
1121 <p>When using the rewrite engine in <code>.htaccess</code> files the
1122 per-directory prefix (which always is the same for a specific
1123 directory) is automatically <em>removed</em> for the pattern matching
1124 and automatically <em>added</em> after the substitution has been
1125 done. This feature is essential for many sorts of rewriting; without
1126 this, you would always have to match the parent directory, which is
1127 not always possible.  There is one exception: If a substitution string
1128 starts with <code>http://</code>, then the directory prefix will
1129 <strong>not</strong> be added, and an external redirect (or proxy
1130 throughput, if using flag <strong>P</strong>) is forced.  See the
1131 <code class="directive"><a href="#rewritebase">RewriteBase</a></code> directive for
1132 more information.</p>
1133
1134 <p>The rewrite engine may also be used in <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> sections with the same
1135 prefix-matching rules as would be applied to <code>.htaccess</code>
1136 files.  It is usually simpler, however, to avoid the prefix substitution
1137 complication by putting the rewrite rules in the main server or
1138 virtual host context, rather than in a <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> section.</p>
1139
1140 <p>Although rewrite rules are syntactically permitted in <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> and <code class="directive"><a href="../mod/core.html#files">&lt;Files&gt;</a></code> sections, this
1141 should never be necessary and is unsupported.</p>
1142
1143 </div>
1144
1145      <p>Here are all possible substitution combinations and their
1146       meanings:</p>
1147
1148       <p><strong>Inside per-server configuration
1149       (<code>httpd.conf</code>)<br />
1150        for request ``<code>GET
1151       /somepath/pathinfo</code>'':</strong><br />
1152       </p>
1153
1154 <table class="bordered">
1155 <tr>
1156 <th>Given Rule</th>
1157 <th>Resulting Substitution</th>
1158 </tr>
1159
1160 <tr>
1161 <td>^/somepath(.*) otherpath$1</td>
1162 <td>invalid, not supported</td>
1163 </tr>
1164
1165 <tr>
1166 <td>^/somepath(.*) otherpath$1  [R]</td>
1167 <td>invalid, not supported</td>
1168 </tr>
1169
1170 <tr>
1171 <td>^/somepath(.*) otherpath$1  [P]</td>
1172 <td>invalid, not supported</td>
1173 </tr>
1174
1175 <tr>
1176 <td>^/somepath(.*) /otherpath$1</td>
1177 <td>/otherpath/pathinfo</td>
1178 </tr>
1179
1180 <tr>
1181 <td>^/somepath(.*) /otherpath$1 [R]</td>
1182 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1183 </tr>
1184
1185 <tr>
1186 <td>^/somepath(.*) /otherpath$1 [P]</td>
1187 <td>doesn't make sense, not supported</td>
1188 </tr>
1189
1190 <tr>
1191 <td>^/somepath(.*) http://thishost/otherpath$1</td>
1192 <td>/otherpath/pathinfo</td>
1193 </tr>
1194
1195 <tr>
1196 <td>^/somepath(.*) http://thishost/otherpath$1 [R]</td>
1197 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1198 </tr>
1199
1200 <tr>
1201 <td>^/somepath(.*) http://thishost/otherpath$1 [P]</td>
1202 <td>doesn't make sense, not supported</td>
1203 </tr>
1204
1205 <tr>
1206 <td>^/somepath(.*) http://otherhost/otherpath$1</td>
1207 <td>http://otherhost/otherpath/pathinfo via external redirection</td>
1208 </tr>
1209
1210 <tr>
1211 <td>^/somepath(.*) http://otherhost/otherpath$1 [R]</td>
1212 <td>http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant)</td>
1213 </tr>
1214
1215 <tr>
1216 <td>^/somepath(.*) http://otherhost/otherpath$1 [P]</td>
1217 <td>http://otherhost/otherpath/pathinfo via internal proxy</td>
1218 </tr>
1219 </table>
1220
1221       <p><strong>Inside per-directory configuration for
1222       <code>/somepath</code><br />
1223        (<code>/physical/path/to/somepath/.htacccess</code>, with
1224       <code>RewriteBase /somepath</code>)<br />
1225        for request ``<code>GET
1226       /somepath/localpath/pathinfo</code>'':</strong><br />
1227      </p>
1228
1229 <table class="bordered">
1230
1231 <tr>
1232 <th>Given Rule</th>
1233 <th>Resulting Substitution</th>
1234 </tr>
1235
1236 <tr>
1237 <td>^localpath(.*) otherpath$1</td>
1238 <td>/somepath/otherpath/pathinfo</td>
1239 </tr>
1240
1241 <tr>
1242 <td>^localpath(.*) otherpath$1  [R]</td>
1243 <td>http://thishost/somepath/otherpath/pathinfo via external
1244 redirection</td>
1245 </tr>
1246
1247 <tr>
1248 <td>^localpath(.*) otherpath$1  [P]</td>
1249 <td>doesn't make sense, not supported</td>
1250 </tr>
1251
1252 <tr>
1253 <td>^localpath(.*) /otherpath$1</td>
1254 <td>/otherpath/pathinfo</td>
1255 </tr>
1256
1257 <tr>
1258 <td>^localpath(.*) /otherpath$1 [R]</td>
1259 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1260 </tr>
1261
1262 <tr>
1263 <td>^localpath(.*) /otherpath$1 [P]</td>
1264 <td>doesn't make sense, not supported</td>
1265 </tr>
1266
1267 <tr>
1268 <td>^localpath(.*) http://thishost/otherpath$1</td>
1269 <td>/otherpath/pathinfo</td>
1270 </tr>
1271
1272 <tr>
1273 <td>^localpath(.*) http://thishost/otherpath$1 [R]</td>
1274 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1275 </tr>
1276
1277 <tr>
1278 <td>^localpath(.*) http://thishost/otherpath$1 [P]</td>
1279 <td>doesn't make sense, not supported</td>
1280 </tr>
1281
1282 <tr>
1283 <td>^localpath(.*) http://otherhost/otherpath$1</td>
1284 <td>http://otherhost/otherpath/pathinfo via external redirection</td>
1285 </tr>
1286
1287 <tr>
1288 <td>^localpath(.*) http://otherhost/otherpath$1 [R]</td>
1289 <td>http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant)</td>
1290 </tr>
1291
1292 <tr>
1293 <td>^localpath(.*) http://otherhost/otherpath$1 [P]</td>
1294 <td>http://otherhost/otherpath/pathinfo via internal proxy</td>
1295 </tr>
1296
1297 </table>
1298
1299
1300 </div>
1301 </div>
1302 <div class="bottomlang">
1303 <p><span>Available Languages: </span><a href="../en/mod/mod_rewrite.html" title="English">&nbsp;en&nbsp;</a> |
1304 <a href="../fr/mod/mod_rewrite.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
1305 </div><div id="footer">
1306 <p class="apache">Copyright 2010 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>
1307 <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>
1308 </body></html>