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