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