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