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