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