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><p>'<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!</p>
 603             <p> This flag <em>only</em> returns information about things
 604             like access control, authentication, and authorization.  This flag
 605             <em>does not</em> return information about the status code the
 606             configured handler (static file, CGI, proxy, etc.) would have
 607             returned.</p> </li>
 608
 609             <li>'<strong>-x</strong>' (has e<strong>x</strong>ecutable
 610             permissions)<br />
 611             Treats the <em>TestString</em> as a pathname and tests
 612             whether or not it exists, and has executable permissions.
 613             These permissions are determined according to
 614             the underlying OS.</li>
 615
 616           </ul>
 617
 618 <div class="note"><h3>Note:</h3>
 619               All of these tests can
 620               also be prefixed by an exclamation mark ('!') to
 621               negate their meaning.
 622 </div>
 623         </li>
 624
 625         <li>
 626            <p>If the <em>TestString</em> has the special value <code>expr</code>, the
 627            <em>CondPattern</em> will be treated as an
 628            <a href="../expr.html">ap_expr</a>.</p>
 629
 630            <p>
 631             In the below example, <code>-strmatch</code> is used to
 632             compare the <code>REFERER</code> against the site hostname,
 633             to block unwanted hotlinking.
 634            </p>
 635
 636            <pre class="prettyprint lang-config">
 637            RewriteCond expr "! %{HTTP_REFERER} -strmatch '*://%{HTTP_HOST}/*'"<br />
 638            RewriteRule ^/images - [F]
 639            </pre>
 640
 641         </li>
 642
 643         <li>You can also set special flags for
 644       <em>CondPattern</em> by appending
 645         <strong><code>[</code><em>flags</em><code>]</code></strong>
 646       as the third argument to the <code>RewriteCond</code>
 647       directive, where <em>flags</em> is a comma-separated list of any of the
 648       following flags:
 649
 650       <ul>
 651         <li>'<strong><code>nocase|NC</code></strong>'
 652         (<strong>n</strong>o <strong>c</strong>ase)<br />
 653         This makes the test case-insensitive - differences
 654         between 'A-Z' and 'a-z' are ignored, both in the
 655         expanded <em>TestString</em> and the <em>CondPattern</em>.
 656         This flag is effective only for comparisons between
 657         <em>TestString</em> and <em>CondPattern</em>. It has no
 658         effect on filesystem and subrequest checks.</li>
 659
 660         <li>
 661           '<strong><code>ornext|OR</code></strong>'
 662           (<strong>or</strong> next condition)<br />
 663           Use this to combine rule conditions with a local OR
 664           instead of the implicit AND. Typical example:
 665
 666 <pre class="prettyprint lang-config">
 667 RewriteCond %{REMOTE_HOST}  ^host1  [OR]
 668 RewriteCond %{REMOTE_HOST}  ^host2  [OR]
 669 RewriteCond %{REMOTE_HOST}  ^host3
 670 RewriteRule ...some special stuff for any of these hosts...
 671 </pre>
 672
 673
 674           Without this flag you would have to write the condition/rule
 675           pair three times.
 676         </li>
 677
 678         <li>'<strong><code>novary|NV</code></strong>'
 679         (<strong>n</strong>o <strong>v</strong>ary)<br />
 680         If a HTTP header is used in the condition, this flag prevents
 681         this header from being added to the Vary header of the response. <br />
 682         Using this flag might break proper caching of the response if
 683         the representation of this response varies on the value of this header.
 684         So this flag should be only used if the meaning of the Vary header
 685         is well understood.
 686         </li>
 687       </ul>
 688       </li>
 689      </ol>
 690
 691       <p><strong>Example:</strong></p>
 692
 693        <p>To rewrite the Homepage of a site according to the
 694         ``<code>User-Agent:</code>'' header of the request, you can
 695         use the following: </p>
 696
 697 <pre class="prettyprint lang-config">
 698 RewriteCond  %{HTTP_USER_AGENT}  (iPhone|Blackberry|Android)
 699 RewriteRule  ^/$                 /homepage.mobile.html  [L]
 700
 701 RewriteRule  ^/$                 /homepage.std.html  [L]
 702 </pre>
 703
 704
 705         <p>Explanation: If you use a browser which identifies itself
 706         as a mobile browser (note that the example is incomplete, as
 707         there are many other mobile platforms), the mobile version of
 708         the homepage is served. Otherwise, the standard page is served.
 709         </p>
 710
 711
 712 </div>
 713 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 714 <div class="directive-section"><h2><a name="RewriteEngine" id="RewriteEngine">RewriteEngine</a> <a name="rewriteengine" id="rewriteengine">Directive</a></h2>
 715 <table class="directive">
 716 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables or disables runtime rewriting engine</td></tr>
 717 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteEngine on|off</code></td></tr>
 718 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteEngine off</code></td></tr>
 719 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 720 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 721 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 722 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 723 </table>
 724
 725       <p>The <code class="directive">RewriteEngine</code> directive enables or
 726       disables the runtime rewriting engine. If it is set to
 727       <code>off</code> this module does no runtime processing at
 728       all. It does not even update the <code>SCRIPT_URx</code>
 729       environment variables.</p>
 730
 731       <p>Use this directive to disable rules in a particular contact,
 732       rather than commenting out all the <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives.</p>
 733
 734       <p>Note that rewrite configurations are not
 735       inherited by virtual hosts. This means that you need to have a
 736       <code>RewriteEngine on</code> directive for each virtual host
 737       in which you wish to use rewrite rules.</p>
 738
 739       <p><code class="directive">RewriteMap</code> directives of the type <code>prg</code>
 740       are not started during server initialization if they're defined in a
 741       context that does not have <code class="directive">RewriteEngine</code>  set to
 742       <code>on</code></p>
 743
 744 </div>
 745 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 746 <div class="directive-section"><h2><a name="RewriteMap" id="RewriteMap">RewriteMap</a> <a name="rewritemap" id="rewritemap">Directive</a></h2>
 747 <table class="directive">
 748 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a mapping function for key-lookup</td></tr>
 749 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
 750 </code></td></tr>
 751 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 752 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 753 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 754 </table>
 755       <p>The <code class="directive">RewriteMap</code> directive defines a
 756       <em>Rewriting Map</em> which can be used inside rule
 757       substitution strings by the mapping-functions to
 758       insert/substitute fields through a key lookup. The source of
 759       this lookup can be of various types.</p>
 760
 761       <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
 762       the name of the map and will be used to specify a
 763       mapping-function for the substitution strings of a rewriting
 764       rule via one of the following constructs:</p>
 765
 766       <p class="indent">
 767         <strong><code>${</code> <em>MapName</em> <code>:</code>
 768         <em>LookupKey</em> <code>}</code><br />
 769          <code>${</code> <em>MapName</em> <code>:</code>
 770         <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
 771         <code>}</code></strong>
 772       </p>
 773
 774       <p>When such a construct occurs, the map <em>MapName</em> is
 775       consulted and the key <em>LookupKey</em> is looked-up. If the
 776       key is found, the map-function construct is substituted by
 777       <em>SubstValue</em>. If the key is not found then it is
 778       substituted by <em>DefaultValue</em> or by the empty string
 779       if no <em>DefaultValue</em> was specified. Empty values
 780       behave as if the key was absent, therefore it is not possible
 781       to distinguish between empty-valued keys and absent keys.</p>
 782
 783       <p>For example, you might define a
 784       <code class="directive">RewriteMap</code> as:</p>
 785
 786       <pre class="prettyprint lang-config">
 787       RewriteMap examplemap txt:/path/to/file/map.txt
 788       </pre>
 789
 790
 791       <p>You would then be able to use this map in a
 792       <code class="directive">RewriteRule</code> as follows:</p>
 793
 794       <pre class="prettyprint lang-config">
 795       RewriteRule ^/ex/(.*) ${examplemap:$1}
 796       </pre>
 797
 798
 799       <p>The following combinations for <em>MapType</em> and
 800       <em>MapSource</em> can be used:</p>
 801
 802     <dl>
 803
 804     <dt>txt</dt>
 805         <dd>A plain text file containing space-separated key-value
 806         pairs, one per line. (<a href="../rewrite/rewritemap.html#txt">Details ...</a>)</dd>
 807
 808     <dt>rnd</dt>
 809         <dd>Randomly selects an entry from a plain text file (<a href="../rewrite/rewritemap.html#rnd">Details ...</a>)</dd>
 810
 811     <dt>dbm</dt>
 812         <dd>Looks up an entry in a dbm file containing name, value
 813         pairs. Hash is constructed from a plain text file format using
 814         the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code>
 815         utility.  (<a href="../rewrite/rewritemap.html#dbm">Details ...</a>)</dd>
 816
 817     <dt>int</dt>
 818         <dd>One of the four available internal functions provided by
 819         <code>RewriteMap</code>: toupper, tolower, escape or
 820         unescape. (<a href="../rewrite/rewritemap.html#int">Details ...</a>)</dd>
 821
 822     <dt>prg</dt>
 823         <dd>Calls an external program or script to process the
 824         rewriting. (<a href="../rewrite/rewritemap.html#prg">Details ...</a>)</dd>
 825
 826     <dt>dbd or fastdbd</dt>
 827         <dd>A SQL SELECT statement to be performed to look up the
 828         rewrite target. (<a href="../rewrite/rewritemap.html#dbd">Details ...</a>)</dd>
 829     </dl>
 830
 831     <p>Further details, and numerous examples, may be found in the <a href="../rewrite/rewritemap.html">RewriteMap HowTo</a></p>
 832
 833
 834 </div>
 835 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 836 <div class="directive-section"><h2><a name="RewriteOptions" id="RewriteOptions">RewriteOptions</a> <a name="rewriteoptions" id="rewriteoptions">Directive</a></h2>
 837 <table class="directive">
 838 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets some special options for the rewrite engine</td></tr>
 839 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteOptions <var>Options</var></code></td></tr>
 840 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 841 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 842 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 843 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</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       <dt><code>MergeBase</code></dt>
 928       <dd>
 929
 930       <p>With this option, the value of <code class="directive"><a href="#rewritebase">RewriteBase</a></code> is copied from where it's explicitly defined
 931       into any sub-directory or sub-location that doesn't define its own
 932       <code class="directive"><a href="#rewritebase">RewriteBase</a></code>. Available in
 933       Apache HTTP Server 2.5 and later only.</p>
 934       </dd>
 935       </dl>
 936
 937
 938 </div>
 939 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 940 <div class="directive-section"><h2><a name="RewriteRule" id="RewriteRule">RewriteRule</a> <a name="rewriterule" id="rewriterule">Directive</a></h2>
 941 <table class="directive">
 942 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines rules for the rewriting engine</td></tr>
 943 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteRule
 944       <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</code></td></tr>
 945 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 946 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 947 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 948 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 949 </table>
 950       <p>The <code class="directive">RewriteRule</code> directive is the real
 951       rewriting workhorse. The directive can occur more than once,
 952       with each instance defining a single rewrite rule. The
 953       order in which these rules are defined is important - this is the order
 954       in which they will be applied at run-time.</p>
 955
 956       <p><a id="patterns" name="patterns"><em>Pattern</em></a> is
 957       a perl compatible <a id="regexp" name="regexp">regular
 958       expression</a>. On the first RewriteRule, it is matched against
 959       the (%-decoded) <a href="./directive-dict.html#Syntax">URL-path</a> (or
 960       <a href="./directive-dict.html#Syntax">file-path</a>, depending
 961       on the context) of the request. Subsequent patterns are matched against the
 962       output of the last matching RewriteRule.</p>
 963
 964 <div class="note"><h3><a id="what_is_matched" name="what_is_matched">What is matched?</a></h3>
 965       <p>In <code class="directive"><a href="../mod/core.html#virtualhost">VirtualHost</a></code> context,
 966       The <em>Pattern</em> will initially be matched against the part of the
 967       URL after the hostname and port, and before the query string (e.g. "/app1/index.html").</p>
 968
 969       <p>In <code class="directive"><a href="../mod/core.html#directory">Directory</a></code> and htaccess context,
 970       the <em>Pattern</em> will initially be matched against the
 971       <em>filesystem</em> path, after removing the prefix that led the server
 972       to the current <code class="directive">RewriteRule</code> (e.g. "app1/index.html"
 973       or "index.html" depending on where the directives are defined).</p>
 974
 975       <p>If you wish to match against the hostname, port, or query string, use a
 976       <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
 977       <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
 978       <code>%{QUERY_STRING}</code> variables respectively.</p>
 979
 980 </div>
 981
 982 <div class="note"><h3>Per-directory Rewrites</h3>
 983 <ul>
 984 <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
 985 complexity.</li>
 986
 987 <li>To enable the rewrite engine in this context, you need to set
 988 "<code>RewriteEngine On</code>" <strong>and</strong>
 989 "<code>Options FollowSymLinks</code>" must be enabled. If your
 990 administrator has disabled override of <code>FollowSymLinks</code> for
 991 a user's directory, then you cannot use the rewrite engine. This
 992 restriction is required for security reasons.</li>
 993
 994 <li>When using the rewrite engine in <code>.htaccess</code> files the
 995 per-directory prefix (which always is the same for a specific
 996 directory) is automatically <em>removed</em> for the RewriteRule pattern matching
 997 and automatically <em>added</em> after any relative (not starting with a
 998 slash or protocol name) substitution encounters the end of a rule set.
 999 See the <code class="directive"><a href="#rewritebase">RewriteBase</a></code>
1000 directive for more information regarding what prefix will be added back to
1001 relative substitutions.</li>
1002
1003 <li> If you wish to match against the full URL-path in a per-directory
1004 (htaccess) RewriteRule, use the <code>%{REQUEST_URI}</code> variable in
1005 a <code class="directive">RewriteCond</code>.</li>
1006
1007 <li>The removed prefix always ends with a slash, meaning the matching occurs against a string which
1008 <em>never</em> has a leading slash.  Therefore, a <em>Pattern</em> with <code>^/</code> never
1009 matches in per-directory context.</li>
1010
1011 <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
1012 should never be necessary and is unsupported.</li>
1013 </ul>
1014 </div>
1015
1016       <p>For some hints on <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
1017       expressions</a>, see
1018       the <a href="../rewrite/intro.html#regex">mod_rewrite
1019       Introduction</a>.</p>
1020
1021       <p>In mod_rewrite, the NOT character
1022       ('<code>!</code>') is also available as a possible pattern
1023       prefix. This enables you to negate a pattern; to say, for instance:
1024       ``<em>if the current URL does <strong>NOT</strong> match this
1025       pattern</em>''. This can be used for exceptional cases, where
1026       it is easier to match the negative pattern, or as a last
1027       default rule.</p>
1028
1029 <div class="note"><h3>Note</h3>
1030 When using the NOT character to negate a pattern, you cannot include
1031 grouped wildcard parts in that pattern. This is because, when the
1032 pattern does NOT match (ie, the negation matches), there are no
1033 contents for the groups. Thus, if negated patterns are used, you
1034 cannot use <code>$N</code> in the substitution string!
1035 </div>
1036
1037       <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
1038       rewrite rule is the string that replaces the original URL-path that
1039       was matched by <em>Pattern</em>.  The <em>Substitution</em> may
1040       be a:</p>
1041
1042       <dl>
1043
1044         <dt>file-system path</dt>
1045
1046         <dd>Designates the location on the file-system of the resource
1047         to be delivered to the client.  Substitutions are only
1048         treated as a file-system path when the rule is configured in
1049         server (virtualhost) context and the first component of the
1050         path in the substitution exists in the file-system</dd>
1051
1052         <dt>URL-path</dt>
1053
1054         <dd>A <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>-relative path to the
1055         resource to be served. Note that <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
1056         tries to guess whether you have specified a file-system path
1057         or a URL-path by checking to see if the first segment of the
1058         path exists at the root of the file-system. For example, if
1059         you specify a <em>Substitution</em> string of
1060         <code>/www/file.html</code>, then this will be treated as a
1061         URL-path <em>unless</em> a directory named <code>www</code>
1062         exists at the root or your file-system (or, in the case of
1063         using rewrites in a <code>.htaccess</code> file, relative to
1064         your document root), in which case it will
1065         be treated as a file-system path. If you wish other
1066         URL-mapping directives (such as <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>) to be applied to the
1067         resulting URL-path, use the <code>[PT]</code> flag as
1068         described below.</dd>
1069
1070         <dt>Absolute URL</dt>
1071
1072         <dd>If an absolute URL is specified,
1073         <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> checks to see whether the
1074         hostname matches the current host. If it does, the scheme and
1075         hostname are stripped out and the resulting path is treated as
1076         a URL-path. Otherwise, an external redirect is performed for
1077         the given URL. To force an external redirect back to the
1078         current host, see the <code>[R]</code> flag below.</dd>
1079
1080         <dt><code>-</code> (dash)</dt>
1081
1082         <dd>A dash indicates that no substitution should be performed
1083         (the existing path is passed through untouched). This is used
1084         when a flag (see below) needs to be applied without changing
1085         the path.</dd>
1086
1087       </dl>
1088
1089       <p>In addition to plain text, the <em>Substitution</em> string can include</p>
1090
1091       <ol>
1092         <li>back-references (<code>$N</code>) to the RewriteRule
1093         pattern</li>
1094
1095         <li>back-references (<code>%N</code>) to the last matched
1096         RewriteCond pattern</li>
1097
1098         <li>server-variables as in rule condition test-strings
1099         (<code>%{VARNAME}</code>)</li>
1100
1101         <li><a href="#mapfunc">mapping-function</a> calls
1102         (<code>${mapname:key|default}</code>)</li>
1103       </ol>
1104
1105       <p>Back-references are identifiers of the form
1106       <code>$</code><strong>N</strong>
1107       (<strong>N</strong>=0..9), which will be replaced
1108       by the contents of the <strong>N</strong>th group of the
1109       matched <em>Pattern</em>. The server-variables are the same
1110       as for the <em>TestString</em> of a <code>RewriteCond</code>
1111       directive. The mapping-functions come from the
1112       <code>RewriteMap</code> directive and are explained there.
1113       These three types of variables are expanded in the order above.</p>
1114
1115       <p>Rewrite rules are applied to the results of previous rewrite
1116       rules, in the order in which they are defined
1117       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
1118       replaced</strong> by the <em>Substitution</em> and the
1119       rewriting process continues until all rules have been applied,
1120       or it is explicitly terminated by an
1121       <a href="../rewrite/flags.html#flag_l"><code><strong>L</strong></code> flag</a>,
1122       or other flag which implies immediate termination, such as
1123       <code><strong>END</strong></code> or
1124       <code><strong>F</strong></code>.</p>
1125
1126      <div class="note"><h3>Modifying the Query String</h3>
1127       <p>By default, the query string is passed through unchanged. You
1128       can, however, create URLs in the substitution string containing
1129       a query string part. Simply use a question mark inside the
1130       substitution string to indicate that the following text should
1131       be re-injected into the query string. When you want to erase an
1132       existing query string, end the substitution string with just a
1133       question mark. To combine new and old query strings, use the
1134       <code>[QSA]</code> flag.</p>
1135      </div>
1136
1137       <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">actions</a> to be performed by
1138       appending <strong><code>[</code><em>flags</em><code>]</code></strong>
1139       as the third argument to the <code>RewriteRule</code>
1140       directive. <em>Flags</em> is a comma-separated list, surround by square
1141       brackets, of any of the flags in the following table. More
1142       details, and examples, for each flag, are available in the <a href="../rewrite/flags.html">Rewrite Flags document</a>.</p>
1143
1144     <table class="bordered">
1145     <tr><th>Flag and syntax</th>
1146         <th>Function</th>
1147     </tr>
1148     <tr>
1149         <td>B</td>
1150         <td>Escape non-alphanumeric characters <em>before</em> applying
1151         the transformation. <em><a href="../rewrite/flags.html#flag_b">details ...</a></em></td>
1152     </tr>
1153     <tr>
1154         <td>chain|C</td>
1155         <td>Rule is chained to the following rule. If the rule fails,
1156         the rule(s) chained to it will be skipped. <em><a href="../rewrite/flags.html#flag_c">details ...</a></em></td>
1157     </tr>
1158     <tr>
1159         <td>cookie|CO=<em>NAME</em>:<em>VAL</em></td>
1160         <td>Sets a cookie in the client browser. Full syntax is:
1161         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>
1162         </td>
1163     </tr>
1164     <tr>
1165         <td>discardpath|DPI</td>
1166         <td>Causes the PATH_INFO portion of the rewritten URI to be
1167         discarded. <em><a href="../rewrite/flags.html#flag_dpi">details
1168         ...</a></em></td>
1169     </tr>
1170     <tr>
1171         <td>env|E=[!]<em>VAR</em>[:<em>VAL</em>]</td>
1172         <td>Causes an environment variable <em>VAR</em> to be set (to the
1173         value <em>VAL</em> if provided). The form !<em>VAR</em> causes
1174         the environment variable <em>VAR</em> to be unset.<em><a href="../rewrite/flags.html#flag_e">details ...</a></em></td>
1175     </tr>
1176     <tr>
1177         <td>forbidden|F</td>
1178         <td>Returns a 403 FORBIDDEN response to the client browser.
1179         <em><a href="../rewrite/flags.html#flag_f">details ...</a></em></td>
1180     </tr>
1181     <tr>
1182         <td>gone|G</td>
1183         <td>Returns a 410 GONE response to the client browser. <em><a href="../rewrite/flags.html#flag_g">details ...</a></em></td>
1184     </tr>
1185     <tr>
1186         <td>Handler|H=<em>Content-handler</em></td>
1187         <td>Causes the resulting URI to be sent to the specified
1188         <em>Content-handler</em> for processing. <em><a href="../rewrite/flags.html#flag_h">details ...</a></em></td>
1189     </tr>
1190     <tr>
1191         <td>last|L</td>
1192         <td>Stop the rewriting process immediately and don't apply any
1193         more rules. Especially note caveats for per-directory and
1194         .htaccess context (see also the END flag). <em><a href="../rewrite/flags.html#flag_end">details ...</a></em></td>
1195     </tr>
1196     <tr>
1197         <td>next|N</td>
1198         <td>Re-run the rewriting process, starting again with the first
1199         rule, using the result of the ruleset so far as a starting
1200         point. <em><a href="../rewrite/flags.html#flag_n">details
1201         ...</a></em></td>
1202     </tr>
1203     <tr>
1204         <td>nocase|NC</td>
1205         <td>Makes the pattern comparison case-insensitive.
1206         <em><a href="../rewrite/flags.html#flag_nc">details ...</a></em></td>
1207     </tr>
1208     <tr>
1209         <td>noescape|NE</td>
1210         <td>Prevent mod_rewrite from applying hexcode escaping of
1211         special characters in the result of the rewrite. <em><a href="../rewrite/flags.html#flag_ne">details ...</a></em></td>
1212     </tr>
1213     <tr>
1214         <td>nosubreq|NS</td>
1215         <td>Causes a rule to be skipped if the current request is an
1216         internal sub-request. <em><a href="../rewrite/flags.html#flag_ns">details ...</a></em></td>
1217     </tr>
1218     <tr>
1219         <td>proxy|P</td>
1220         <td>Force the substitution URL to be internally sent as a proxy
1221         request. <em><a href="../rewrite/flags.html#flag_p">details
1222         ...</a></em></td>
1223     </tr>
1224     <tr>
1225         <td>passthrough|PT</td>
1226         <td>Forces the resulting URI to be passed back to the URL
1227         mapping engine for processing of other URI-to-filename
1228         translators, such as <code>Alias</code> or
1229         <code>Redirect</code>. <em><a href="../rewrite/flags.html#flag_pt">details ...</a></em></td>
1230     </tr>
1231     <tr>
1232         <td>qsappend|QSA</td>
1233         <td>Appends any query string from the original request URL to
1234         any query string created in the rewrite target.<em><a href="../rewrite/flags.html#flag_qsa">details ...</a></em></td>
1235     </tr>
1236     <tr>
1237         <td>qsdiscard|QSD</td>
1238         <td>Discard any query string attached to the incoming URI.
1239         <em><a href="../rewrite/flags.html#flag_qsd">details
1240         ...</a></em></td>
1241     </tr>
1242     <tr>
1243         <td>redirect|R[=<em>code</em>]</td>
1244         <td>Forces an external redirect, optionally with the specified
1245         HTTP status code. <em><a href="../rewrite/flags.html#flag_r">details ...</a></em>
1246         </td>
1247     </tr>
1248     <tr>
1249         <td>END</td>
1250         <td>Stop the rewriting process immediately and don't apply any
1251         more rules. Also prevents further execution of rewrite rules
1252         in per-directory and .htaccess context. (Available in 2.3.9 and later)
1253         <em><a href="../rewrite/flags.html#flag_l">details ...</a></em></td>
1254     </tr>
1255     <tr>
1256         <td>skip|S=<em>num</em></td>
1257         <td>Tells the rewriting engine to skip the next <em>num</em>
1258         rules if the current rule matches. <em><a href="../rewrite/flags.html#flag_s">details ...</a></em></td>
1259     </tr>
1260     <tr>
1261         <td>type|T=<em>MIME-type</em></td>
1262         <td>Force the <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> of the target file
1263         to be the specified type. <em><a href="../rewrite/flags.html#flag_t">details ...</a></em></td>
1264     </tr>
1265     </table>
1266
1267 <div class="note"><h3>Home directory expansion</h3>
1268 <p> When the substitution string begins with a string
1269 resembling "/~user" (via explicit text or backreferences), mod_rewrite performs
1270 home directory expansion independent of the presence or configuration
1271 of <code class="module"><a href="../mod/mod_userdir.html">mod_userdir</a></code>.</p>
1272
1273 <p> This expansion does not occur when the <em>PT</em>
1274 flag is used on the <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
1275 directive.</p>
1276 </div>
1277
1278
1279      <p>Here are all possible substitution combinations and their
1280       meanings:</p>
1281
1282       <p><strong>Inside per-server configuration
1283       (<code>httpd.conf</code>)<br />
1284        for request ``<code>GET
1285       /somepath/pathinfo</code>'':</strong><br />
1286       </p>
1287
1288 <table class="bordered">
1289 <tr>
1290 <th>Given Rule</th>
1291 <th>Resulting Substitution</th>
1292 </tr>
1293
1294 <tr>
1295 <td>^/somepath(.*) otherpath$1</td>
1296 <td>invalid, not supported</td>
1297 </tr>
1298
1299 <tr>
1300 <td>^/somepath(.*) otherpath$1  [R]</td>
1301 <td>invalid, not supported</td>
1302 </tr>
1303
1304 <tr>
1305 <td>^/somepath(.*) otherpath$1  [P]</td>
1306 <td>invalid, not supported</td>
1307 </tr>
1308
1309 <tr>
1310 <td>^/somepath(.*) /otherpath$1</td>
1311 <td>/otherpath/pathinfo</td>
1312 </tr>
1313
1314 <tr>
1315 <td>^/somepath(.*) /otherpath$1 [R]</td>
1316 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1317 </tr>
1318
1319 <tr>
1320 <td>^/somepath(.*) /otherpath$1 [P]</td>
1321 <td>doesn't make sense, not supported</td>
1322 </tr>
1323
1324 <tr>
1325 <td>^/somepath(.*) http://thishost/otherpath$1</td>
1326 <td>/otherpath/pathinfo</td>
1327 </tr>
1328
1329 <tr>
1330 <td>^/somepath(.*) http://thishost/otherpath$1 [R]</td>
1331 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1332 </tr>
1333
1334 <tr>
1335 <td>^/somepath(.*) http://thishost/otherpath$1 [P]</td>
1336 <td>doesn't make sense, not supported</td>
1337 </tr>
1338
1339 <tr>
1340 <td>^/somepath(.*) http://otherhost/otherpath$1</td>
1341 <td>http://otherhost/otherpath/pathinfo via external redirection</td>
1342 </tr>
1343
1344 <tr>
1345 <td>^/somepath(.*) http://otherhost/otherpath$1 [R]</td>
1346 <td>http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant)</td>
1347 </tr>
1348
1349 <tr>
1350 <td>^/somepath(.*) http://otherhost/otherpath$1 [P]</td>
1351 <td>http://otherhost/otherpath/pathinfo via internal proxy</td>
1352 </tr>
1353 </table>
1354
1355       <p><strong>Inside per-directory configuration for
1356       <code>/somepath</code><br />
1357        (<code>/physical/path/to/somepath/.htaccess</code>, with
1358       <code>RewriteBase /somepath</code>)<br />
1359        for request ``<code>GET
1360       /somepath/localpath/pathinfo</code>'':</strong><br />
1361      </p>
1362
1363 <table class="bordered">
1364
1365 <tr>
1366 <th>Given Rule</th>
1367 <th>Resulting Substitution</th>
1368 </tr>
1369
1370 <tr>
1371 <td>^localpath(.*) otherpath$1</td>
1372 <td>/somepath/otherpath/pathinfo</td>
1373 </tr>
1374
1375 <tr>
1376 <td>^localpath(.*) otherpath$1  [R]</td>
1377 <td>http://thishost/somepath/otherpath/pathinfo via external
1378 redirection</td>
1379 </tr>
1380
1381 <tr>
1382 <td>^localpath(.*) otherpath$1  [P]</td>
1383 <td>doesn't make sense, not supported</td>
1384 </tr>
1385
1386 <tr>
1387 <td>^localpath(.*) /otherpath$1</td>
1388 <td>/otherpath/pathinfo</td>
1389 </tr>
1390
1391 <tr>
1392 <td>^localpath(.*) /otherpath$1 [R]</td>
1393 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1394 </tr>
1395
1396 <tr>
1397 <td>^localpath(.*) /otherpath$1 [P]</td>
1398 <td>doesn't make sense, not supported</td>
1399 </tr>
1400
1401 <tr>
1402 <td>^localpath(.*) http://thishost/otherpath$1</td>
1403 <td>/otherpath/pathinfo</td>
1404 </tr>
1405
1406 <tr>
1407 <td>^localpath(.*) http://thishost/otherpath$1 [R]</td>
1408 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1409 </tr>
1410
1411 <tr>
1412 <td>^localpath(.*) http://thishost/otherpath$1 [P]</td>
1413 <td>doesn't make sense, not supported</td>
1414 </tr>
1415
1416 <tr>
1417 <td>^localpath(.*) http://otherhost/otherpath$1</td>
1418 <td>http://otherhost/otherpath/pathinfo via external redirection</td>
1419 </tr>
1420
1421 <tr>
1422 <td>^localpath(.*) http://otherhost/otherpath$1 [R]</td>
1423 <td>http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant)</td>
1424 </tr>
1425
1426 <tr>
1427 <td>^localpath(.*) http://otherhost/otherpath$1 [P]</td>
1428 <td>http://otherhost/otherpath/pathinfo via internal proxy</td>
1429 </tr>
1430
1431 </table>
1432
1433
1434 </div>
1435 </div>
1436 <div class="bottomlang">
1437 <p><span>Available Languages: </span><a href="../en/mod/mod_rewrite.html" title="English">&nbsp;en&nbsp;</a> |
1438 <a href="../fr/mod/mod_rewrite.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
1439 </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>
1440 <script type="text/javascript"><!--//--><![CDATA[//><!--
1441 var comments_shortname = 'httpd';
1442 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_rewrite.html';
1443 (function(w, d) {
1444     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
1445         d.write('<div id="comments_thread"><\/div>');
1446         var s = d.createElement('script');
1447         s.type = 'text/javascript';
1448         s.async = true;
1449         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
1450         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
1451     }
1452     else {
1453         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
1454     }
1455 })(window, document);
1456 //--><!]]></script></div><div id="footer">
1457 <p class="apache">Copyright 2014 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>
1458 <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[//><!--
1459 if (typeof(prettyPrint) !== 'undefined') {
1460     prettyPrint();
1461 }
1462 //--><!]]></script>
1463 </body></html>