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 alert 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. Empty values
 731       behave as if the key was absent, therefore it is not possible
 732       to distinguish between empty-valued keys and absent keys.</p>
 733
 734       <p>For example, you might define a
 735       <code class="directive">RewriteMap</code> as:</p>
 736
 737       <div class="example"><p><code>
 738       RewriteMap examplemap txt:/path/to/file/map.txt
 739       </code></p></div>
 740
 741       <p>You would then be able to use this map in a
 742       <code class="directive">RewriteRule</code> as follows:</p>
 743
 744       <div class="example"><p><code>
 745       RewriteRule ^/ex/(.*) ${examplemap:$1}
 746       </code></p></div>
 747
 748       <p>The following combinations for <em>MapType</em> and
 749       <em>MapSource</em> can be used:</p>
 750
 751     <dl>
 752
 753     <dt>txt</dt>
 754         <dd>A plain text file containing space-separated key-value
 755         pairs, one per line. (<a href="../rewrite/rewritemap.html#txt">Details ...</a>)</dd>
 756
 757     <dt>rnd</dt>
 758         <dd>Randomly selects an entry from a plain text file (<a href="../rewrite/rewritemap.html#rnd">Details ...</a>)</dd>
 759
 760     <dt>dbm</dt>
 761         <dd>Looks up an entry in a dbm file containing name, value
 762         pairs. Hash is constructed from a plain text file format using
 763         the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code>
 764         utility.  (<a href="../rewrite/rewritemap.html#dbm">Details ...</a>)</dd>
 765
 766     <dt>int</dt>
 767         <dd>One of the four available internal functions provided by
 768         <code>RewriteMap</code>: toupper, tolower, escape or
 769         unescape. (<a href="../rewrite/rewritemap.html#int">Details ...</a>)</dd>
 770
 771     <dt>prg</dt>
 772         <dd>Calls an external program or script to process the
 773         rewriting. (<a href="../rewrite/rewritemap.html#prg">Details ...</a>)</dd>
 774
 775     <dt>dbd or fastdbd</dt>
 776         <dd>A SQL SELECT statement to be performed to look up the
 777         rewrite target. (<a href="../rewrite/rewritemap.html#dbd">Details ...</a>)</dd>
 778     </dl>
 779
 780     <p>Further details, and numerous examples, may be found in the <a href="../rewrite/rewritemap.html">RewriteMap HowTo</a></p>
 781
 782
 783 </div>
 784 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 785 <div class="directive-section"><h2><a name="RewriteOptions" id="RewriteOptions">RewriteOptions</a> <a name="rewriteoptions" id="rewriteoptions">Directive</a></h2>
 786 <table class="directive">
 787 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets some special options for the rewrite engine</td></tr>
 788 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteOptions <var>Options</var></code></td></tr>
 789 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 790 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 791 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 792 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 793 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><code>MaxRedirects</code> is no longer available in version 2.1 and
 794 later</td></tr>
 795 </table>
 796
 797       <p>The <code class="directive">RewriteOptions</code> directive sets some
 798       special options for the current per-server or per-directory
 799       configuration. The <em>Option</em> string can currently
 800       only be one of the following:</p>
 801
 802       <dl>
 803       <dt><code>inherit</code></dt>
 804       <dd>
 805
 806       <p>This forces the current configuration to inherit the
 807       configuration of the parent. In per-virtual-server context,
 808       this means that the maps, conditions and rules of the main
 809       server are inherited. In per-directory context this means
 810       that conditions and rules of the parent directory's
 811       <code>.htaccess</code> configuration or
 812       <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code>
 813       sections are inherited. The inherited rules are virtually copied
 814       to the section where this directive is being used. If used in
 815       combination with local rules, the inherited rules are copied behind
 816       the local rules. The position of this directive - below or above
 817       of local rules - has no influence on this behavior. If local
 818       rules forced the rewriting to stop, the inherited rules won't
 819       be processed.</p>
 820
 821       <div class="warning">
 822       Rules inherited from the parent scope are applied
 823       <strong>after</strong> rules specified in the child scope.
 824       </div>
 825       </dd>
 826       </dl>
 827
 828 </div>
 829 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 830 <div class="directive-section"><h2><a name="RewriteRule" id="RewriteRule">RewriteRule</a> <a name="rewriterule" id="rewriterule">Directive</a></h2>
 831 <table class="directive">
 832 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines rules for the rewriting engine</td></tr>
 833 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteRule
 834       <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</code></td></tr>
 835 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 836 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 837 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 838 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 839 </table>
 840       <p>The <code class="directive">RewriteRule</code> directive is the real
 841       rewriting workhorse. The directive can occur more than once,
 842       with each instance defining a single rewrite rule. The
 843       order in which these rules are defined is important - this is the order
 844       in which they will be applied at run-time.</p>
 845
 846       <p><a id="patterns" name="patterns"><em>Pattern</em></a> is
 847       a perl compatible <a id="regexp" name="regexp">regular
 848       expression</a>. On the first RewriteRule it is applied to the (%-encoded)
 849       <a href="./directive-dict.html#Syntax">URL-path</a> of the request;
 850       subsequent patterns are applied to the output of the last matched
 851       RewriteRule.</p>
 852
 853 <div class="note"><h3>What is matched?</h3>
 854       <p>The <em>Pattern</em> will initially be matched against the part of the
 855       URL after the hostname and port, and before the query string.</p>
 856
 857       <p>When the RewriteRule appears in per-directory (htaccess) context, the
 858       <em>Pattern</em> is matched against what remains of the URL after removing
 859       the prefix that lead Apache httpd to the current rules (see the
 860       <code class="directive"><a href="#rewritebase">RewriteBase</a></code>).  The removed prefix
 861       always ends with a slash, meaning the matching occurs against a string which
 862       never has a leading slash.  A <em>Pattern</em> with <code>^/</code> never
 863       matches in per-directory context.</p>
 864
 865       <p>If you wish to match against the hostname, port, or query string, use a
 866       <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
 867       <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
 868       <code>%{QUERY_STRING}</code> variables respectively. If you wish to
 869       match against the full URL-path in a per-directory (htaccess) RewriteRule,
 870       use the <code>%{REQUEST_URI}</code> variable.</p>
 871
 872 </div>
 873
 874       <p>For some hints on <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
 875       expressions</a>, see
 876       the <a href="../rewrite/intro.html#regex">mod_rewrite
 877       Introduction</a>.</p>
 878
 879       <p>In mod_rewrite, the NOT character
 880       ('<code>!</code>') is also available as a possible pattern
 881       prefix. This enables you to negate a pattern; to say, for instance:
 882       ``<em>if the current URL does <strong>NOT</strong> match this
 883       pattern</em>''. This can be used for exceptional cases, where
 884       it is easier to match the negative pattern, or as a last
 885       default rule.</p>
 886
 887 <div class="note"><h3>Note</h3>
 888 When using the NOT character to negate a pattern, you cannot include
 889 grouped wildcard parts in that pattern. This is because, when the
 890 pattern does NOT match (ie, the negation matches), there are no
 891 contents for the groups. Thus, if negated patterns are used, you
 892 cannot use <code>$N</code> in the substitution string!
 893 </div>
 894
 895       <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
 896       rewrite rule is the string that replaces the original URL-path that
 897       was matched by <em>Pattern</em>.  The <em>Substitution</em> may
 898       be a:</p>
 899
 900       <dl>
 901
 902         <dt>file-system path</dt>
 903
 904         <dd>Designates the location on the file-system of the resource
 905         to be delivered to the client.</dd>
 906
 907         <dt>URL-path</dt>
 908
 909         <dd>A <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>-relative path to the
 910         resource to be served. Note that <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
 911         tries to guess whether you have specified a file-system path
 912         or a URL-path by checking to see if the first segment of the
 913         path exists at the root of the file-system. For example, if
 914         you specify a <em>Substitution</em> string of
 915         <code>/www/file.html</code>, then this will be treated as a
 916         URL-path <em>unless</em> a directory named <code>www</code>
 917         exists at the root or your file-system, in which case it will
 918         be treated as a file-system path. If you wish other
 919         URL-mapping directives (such as <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>) to be applied to the
 920         resulting URL-path, use the <code>[PT]</code> flag as
 921         described below.</dd>
 922
 923         <dt>Absolute URL</dt>
 924
 925         <dd>If an absolute URL is specified,
 926         <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> checks to see whether the
 927         hostname matches the current host. If it does, the scheme and
 928         hostname are stripped out and the resulting path is treated as
 929         a URL-path. Otherwise, an external redirect is performed for
 930         the given URL. To force an external redirect back to the
 931         current host, see the <code>[R]</code> flag below.</dd>
 932
 933         <dt><code>-</code> (dash)</dt>
 934
 935         <dd>A dash indicates that no substitution should be performed
 936         (the existing path is passed through untouched). This is used
 937         when a flag (see below) needs to be applied without changing
 938         the path.</dd>
 939
 940       </dl>
 941
 942       <p>In addition to plain text, the <em>Substition</em> string can include</p>
 943
 944       <ol>
 945         <li>back-references (<code>$N</code>) to the RewriteRule
 946         pattern</li>
 947
 948         <li>back-references (<code>%N</code>) to the last matched
 949         RewriteCond pattern</li>
 950
 951         <li>server-variables as in rule condition test-strings
 952         (<code>%{VARNAME}</code>)</li>
 953
 954         <li><a href="#mapfunc">mapping-function</a> calls
 955         (<code>${mapname:key|default}</code>)</li>
 956       </ol>
 957
 958       <p>Back-references are identifiers of the form
 959       <code>$</code><strong>N</strong>
 960       (<strong>N</strong>=0..9), which will be replaced
 961       by the contents of the <strong>N</strong>th group of the
 962       matched <em>Pattern</em>. The server-variables are the same
 963       as for the <em>TestString</em> of a <code>RewriteCond</code>
 964       directive. The mapping-functions come from the
 965       <code>RewriteMap</code> directive and are explained there.
 966       These three types of variables are expanded in the order above.</p>
 967
 968       <p>As already mentioned, all rewrite rules are
 969       applied to the <em>Substitution</em> (in the order in which
 970       they are defined
 971       in the config file). The URL is <strong>completely
 972       replaced</strong> by the <em>Substitution</em> and the
 973       rewriting process continues until all rules have been applied,
 974       or it is explicitly terminated by a
 975       <code><strong>L</strong></code> flag.</p>
 976
 977      <div class="note"><h3>Modifying the Query String</h3>
 978       <p>By default, the query string is passed through unchanged. You
 979       can, however, create URLs in the substitution string containing
 980       a query string part. Simply use a question mark inside the
 981       substitution string to indicate that the following text should
 982       be re-injected into the query string. When you want to erase an
 983       existing query string, end the substitution string with just a
 984       question mark. To combine new and old query strings, use the
 985       <code>[QSA]</code> flag.</p>
 986      </div>
 987
 988       <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">actions</a> to be performed by
 989       appending <strong><code>[</code><em>flags</em><code>]</code></strong>
 990       as the third argument to the <code>RewriteRule</code>
 991       directive. <em>Flags</em> is a comma-separated list, surround by square
 992       brackets, of any of the flags in the following table. More
 993       details, and examples, for each flag, are available in the <a href="../rewrite/flags.html">Rewrite Flags document</a>.</p>
 994
 995     <table class="bordered">
 996     <tr><th>Flag and syntax</th>
 997         <th>Function</th>
 998     </tr>
 999     <tr>
1000         <td>B</td>
1001         <td>Escape non-alphanumeric characters <em>before</em> applying
1002         the transformation. <em><a href="../rewrite/flags.html#flag_b">details ...</a></em></td>
1003     </tr>
1004     <tr>
1005         <td>chain|C</td>
1006         <td>Rule is chained to the following rule. If the rule fails,
1007         the rule(s) chained to it will be skipped. <em><a href="../rewrite/flags.html#flag_c">details ...</a></em></td>
1008     </tr>
1009     <tr>
1010         <td>cookie|CO=<em>NAME</em>:<em>VAL</em></td>
1011         <td>Sets a cookie in the client browser. Full syntax is:
1012         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>
1013         </td>
1014     </tr>
1015     <tr>
1016         <td>discardpathinfo|DPI</td>
1017         <td>Causes the PATH_INFO portion of the rewritten URI to be
1018         discarded. <em><a href="../rewrite/flags.html#flag_dpi">details
1019         ...</a></em></td>
1020     </tr>
1021     <tr>
1022         <td>env|E=<em>VAR</em>[:<em>VAL</em>]</td>
1023         <td>Causes an environment variable <em>VAR</em> to be set (to the
1024         value <em>VAL</em> if provided). <em><a href="../rewrite/flags.html#flag_e">details ...</a></em></td>
1025     </tr>
1026     <tr>
1027         <td>forbidden|F</td>
1028         <td>Returns a 403 FORBIDDEN response to the client browser.
1029         <em><a href="../rewrite/flags.html#flag_f">details ...</a></em></td>
1030     </tr>
1031     <tr>
1032         <td>gone|G</td>
1033         <td>Returns a 410 GONE response to the client browser. <em><a href="../rewrite/flags.html#flag_g">details ...</a></em></td>
1034     </tr>
1035     <tr>
1036         <td>Handler|H=<em>Content-handler</em></td>
1037         <td>Causes the resulting URI to be sent to the specified
1038         <em>Content-handler</em> for processing. <em><a href="../rewrite/flags.html#flag_h">details ...</a></em></td>
1039     </tr>
1040     <tr>
1041         <td>last|L</td>
1042         <td>Stop the rewriting process immediately and don't apply any
1043         more rules. Especially note caveats for per-directory and
1044         .htaccess context (see also the END flag). <em><a href="../rewrite/flags.html#flag_l">details ...</a></em></td>
1045     </tr>
1046     <tr>
1047         <td>next|N</td>
1048         <td>Re-run the rewriting process, starting again with the first
1049         rule, using the result of the ruleset so far as a starting
1050         point. <em><a href="../rewrite/flags.html#flag_n">details
1051         ...</a></em></td>
1052     </tr>
1053     <tr>
1054         <td>nocase|NC</td>
1055         <td>Makes the pattern pattern comparison case-insensitive.
1056         <em><a href="../rewrite/flags.html#flag_nc">details ...</a></em></td>
1057     </tr>
1058     <tr>
1059         <td>noescape|NE</td>
1060         <td>Prevent mod_rewrite from applying hexcode escaping of
1061         special characters in the result of the rewrite. <em><a href="../rewrite/flags.html#flag_ne">details ...</a></em></td>
1062     </tr>
1063     <tr>
1064         <td>nosubreq|NS</td>
1065         <td>Causes a rule to be skipped if the current request is an
1066         internal sub-request. <em><a href="../rewrite/flags.html#flag_ns">details ...</a></em></td>
1067     </tr>
1068     <tr>
1069         <td>proxy|P</td>
1070         <td>Force the substitution URL to be internally sent as a proxy
1071         request. <em><a href="../rewrite/flags.html#flag_p">details
1072         ...</a></em></td>
1073     </tr>
1074     <tr>
1075         <td>passthrough|PT</td>
1076         <td>Forces the resulting URI to be passed back to the URL
1077         mapping engine for processing of other URI-to-filename
1078         translators, such as <code>Alias</code> or
1079         <code>Redirect</code>. <em><a href="../rewrite/flags.html#flag_pt">details ...</a></em></td>
1080     </tr>
1081     <tr>
1082         <td>qsappend|QSA</td>
1083         <td>Appends any query string created in the rewrite target to
1084         any query string that was in the original request URL. <em><a href="../rewrite/flags.html#flag_qsa">details ...</a></em></td>
1085     </tr>
1086     <tr>
1087         <td>qsdiscard|QSD</td>
1088         <td>Discard any query string attached to the incoming URI.
1089         <em><a href="../rewrite/flags.html#flag_qsd">details
1090         ...</a></em></td>
1091     </tr>
1092     <tr>
1093         <td>redirect|R[=<em>code</em>]</td>
1094         <td>Forces an external redirect, optionally with the specified
1095         HTTP status code. <em><a href="../rewrite/flags.html#flag_r">details ...</a></em>
1096         </td>
1097     </tr>
1098     <tr>
1099         <td>END</td>
1100         <td>Stop the rewriting process immediately and don't apply any
1101         more rules. Also prevents further execution of rewrite rules
1102         in per-directory and .htaccess context. (Available in 2.3.9 and later)
1103         <em><a href="../rewrite/flags.html#flag_l">details ...</a></em></td>
1104     </tr>
1105     <tr>
1106         <td>skip|S=<em>num</em></td>
1107         <td>Tells the rewriting engine to skip the next <em>num</em>
1108         rules if the current rule matches. <em><a href="../rewrite/flags.html#flag_s">details ...</a></em></td>
1109     </tr>
1110     <tr>
1111         <td>tyle|T=<em>MIME-type</em></td>
1112         <td>Force the <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> of the target file
1113         to be the specified type. <em><a href="../rewrite/flags.html#flag_t">details ...</a></em></td>
1114     </tr>
1115     </table>
1116
1117 <div class="note"><h3>Home directory expansion</h3>
1118 <p> When the substitution string begins with a string
1119 resembling "/~user" (via explicit text or backreferences), mod_rewrite performs
1120 home directory expansion independent of the presence or configuration
1121 of <code class="module"><a href="../mod/mod_userdir.html">mod_userdir</a></code>.</p>
1122
1123 <p> This expansion does not occur when the <em>PT</em>
1124 flag is used on the <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
1125 directive.</p>
1126 </div>
1127
1128 <div class="note"><h3>Per-directory Rewrites</h3>
1129
1130 <p>The rewrite engine may be used in <a href="../howto/htaccess.html">.htaccess</a> files.  To enable the
1131 rewrite engine for these files you need to set
1132 "<code>RewriteEngine On</code>" <strong>and</strong>
1133 "<code>Options FollowSymLinks</code>" must be enabled. If your
1134 administrator has disabled override of <code>FollowSymLinks</code> for
1135 a user's directory, then you cannot use the rewrite engine. This
1136 restriction is required for security reasons.</p>
1137
1138 <p>When using the rewrite engine in <code>.htaccess</code> files the
1139 per-directory prefix (which always is the same for a specific
1140 directory) is automatically <em>removed</em> for the pattern matching
1141 and automatically <em>added</em> after the substitution has been
1142 done. This feature is essential for many sorts of rewriting; without
1143 this, you would always have to match the parent directory, which is
1144 not always possible.  There is one exception: If a substitution string
1145 starts with <code>http://</code>, then the directory prefix will
1146 <strong>not</strong> be added, and an external redirect (or proxy
1147 throughput, if using flag <strong>P</strong>) is forced.  See the
1148 <code class="directive"><a href="#rewritebase">RewriteBase</a></code> directive for
1149 more information.</p>
1150
1151 <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
1152 prefix-matching rules as would be applied to <code>.htaccess</code>
1153 files.  It is usually simpler, however, to avoid the prefix substitution
1154 complication by putting the rewrite rules in the main server or
1155 virtual host context, rather than in a <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> section.</p>
1156
1157 <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
1158 should never be necessary and is unsupported.</p>
1159
1160 </div>
1161
1162      <p>Here are all possible substitution combinations and their
1163       meanings:</p>
1164
1165       <p><strong>Inside per-server configuration
1166       (<code>httpd.conf</code>)<br />
1167        for request ``<code>GET
1168       /somepath/pathinfo</code>'':</strong><br />
1169       </p>
1170
1171 <table class="bordered">
1172 <tr>
1173 <th>Given Rule</th>
1174 <th>Resulting Substitution</th>
1175 </tr>
1176
1177 <tr>
1178 <td>^/somepath(.*) otherpath$1</td>
1179 <td>invalid, not supported</td>
1180 </tr>
1181
1182 <tr>
1183 <td>^/somepath(.*) otherpath$1  [R]</td>
1184 <td>invalid, not supported</td>
1185 </tr>
1186
1187 <tr>
1188 <td>^/somepath(.*) otherpath$1  [P]</td>
1189 <td>invalid, not supported</td>
1190 </tr>
1191
1192 <tr>
1193 <td>^/somepath(.*) /otherpath$1</td>
1194 <td>/otherpath/pathinfo</td>
1195 </tr>
1196
1197 <tr>
1198 <td>^/somepath(.*) /otherpath$1 [R]</td>
1199 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1200 </tr>
1201
1202 <tr>
1203 <td>^/somepath(.*) /otherpath$1 [P]</td>
1204 <td>doesn't make sense, not supported</td>
1205 </tr>
1206
1207 <tr>
1208 <td>^/somepath(.*) http://thishost/otherpath$1</td>
1209 <td>/otherpath/pathinfo</td>
1210 </tr>
1211
1212 <tr>
1213 <td>^/somepath(.*) http://thishost/otherpath$1 [R]</td>
1214 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1215 </tr>
1216
1217 <tr>
1218 <td>^/somepath(.*) http://thishost/otherpath$1 [P]</td>
1219 <td>doesn't make sense, not supported</td>
1220 </tr>
1221
1222 <tr>
1223 <td>^/somepath(.*) http://otherhost/otherpath$1</td>
1224 <td>http://otherhost/otherpath/pathinfo via external redirection</td>
1225 </tr>
1226
1227 <tr>
1228 <td>^/somepath(.*) http://otherhost/otherpath$1 [R]</td>
1229 <td>http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant)</td>
1230 </tr>
1231
1232 <tr>
1233 <td>^/somepath(.*) http://otherhost/otherpath$1 [P]</td>
1234 <td>http://otherhost/otherpath/pathinfo via internal proxy</td>
1235 </tr>
1236 </table>
1237
1238       <p><strong>Inside per-directory configuration for
1239       <code>/somepath</code><br />
1240        (<code>/physical/path/to/somepath/.htacccess</code>, with
1241       <code>RewriteBase /somepath</code>)<br />
1242        for request ``<code>GET
1243       /somepath/localpath/pathinfo</code>'':</strong><br />
1244      </p>
1245
1246 <table class="bordered">
1247
1248 <tr>
1249 <th>Given Rule</th>
1250 <th>Resulting Substitution</th>
1251 </tr>
1252
1253 <tr>
1254 <td>^localpath(.*) otherpath$1</td>
1255 <td>/somepath/otherpath/pathinfo</td>
1256 </tr>
1257
1258 <tr>
1259 <td>^localpath(.*) otherpath$1  [R]</td>
1260 <td>http://thishost/somepath/otherpath/pathinfo via external
1261 redirection</td>
1262 </tr>
1263
1264 <tr>
1265 <td>^localpath(.*) otherpath$1  [P]</td>
1266 <td>doesn't make sense, not supported</td>
1267 </tr>
1268
1269 <tr>
1270 <td>^localpath(.*) /otherpath$1</td>
1271 <td>/otherpath/pathinfo</td>
1272 </tr>
1273
1274 <tr>
1275 <td>^localpath(.*) /otherpath$1 [R]</td>
1276 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1277 </tr>
1278
1279 <tr>
1280 <td>^localpath(.*) /otherpath$1 [P]</td>
1281 <td>doesn't make sense, not supported</td>
1282 </tr>
1283
1284 <tr>
1285 <td>^localpath(.*) http://thishost/otherpath$1</td>
1286 <td>/otherpath/pathinfo</td>
1287 </tr>
1288
1289 <tr>
1290 <td>^localpath(.*) http://thishost/otherpath$1 [R]</td>
1291 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1292 </tr>
1293
1294 <tr>
1295 <td>^localpath(.*) http://thishost/otherpath$1 [P]</td>
1296 <td>doesn't make sense, not supported</td>
1297 </tr>
1298
1299 <tr>
1300 <td>^localpath(.*) http://otherhost/otherpath$1</td>
1301 <td>http://otherhost/otherpath/pathinfo via external redirection</td>
1302 </tr>
1303
1304 <tr>
1305 <td>^localpath(.*) http://otherhost/otherpath$1 [R]</td>
1306 <td>http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant)</td>
1307 </tr>
1308
1309 <tr>
1310 <td>^localpath(.*) http://otherhost/otherpath$1 [P]</td>
1311 <td>http://otherhost/otherpath/pathinfo via internal proxy</td>
1312 </tr>
1313
1314 </table>
1315
1316
1317 </div>
1318 </div>
1319 <div class="bottomlang">
1320 <p><span>Available Languages: </span><a href="../en/mod/mod_rewrite.html" title="English">&nbsp;en&nbsp;</a> |
1321 <a href="../fr/mod/mod_rewrite.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
1322 </div><div id="footer">
1323 <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>
1324 <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>
1325 </body></html>