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