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.min.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">      LogLevel alert rewrite:trace3</pre>
  88 </div>
  89
  90     <div class="note"><h3>RewriteLog</h3>
  91       <p>Those familiar with earlier versions of
  92       <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> will no doubt be looking for the
  93       <code>RewriteLog</code> and <code>RewriteLogLevel</code>
  94       directives. This functionality has been completely replaced by the
  95       new per-module logging configuration mentioned above.
  96       </p>
  97
  98       <p>To get just the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>-specific log
  99       messages, pipe the log file through grep:</p>
 100     <div class="example"><p><code>
 101     tail -f error_log|fgrep '[rewrite:'
 102     </code></p></div>
 103     </div>
 104
 105 </div>
 106 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 107 <div class="directive-section"><h2><a name="RewriteBase" id="RewriteBase">RewriteBase</a> <a name="rewritebase" id="rewritebase">Directive</a></h2>
 108 <table class="directive">
 109 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the base URL for per-directory rewrites</td></tr>
 110 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteBase <em>URL-path</em></code></td></tr>
 111 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>None</code></td></tr>
 112 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 113 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 114 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 115 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 116 </table>
 117       <p>The <code class="directive">RewriteBase</code> directive specifies the
 118       URL prefix to be used for per-directory (htaccess)
 119       <code class="directive">RewriteRule</code> directives that substitute a relative
 120       path.</p>
 121       <p> This directive is <em>required</em> when you use a relative path
 122       in a substitution in per-directory (htaccess) context unless either
 123       of the following conditions are true:</p>
 124       <ul>
 125           <li> The original request, and the substitution, are underneath the
 126                <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>
 127                (as opposed to reachable by other means, such as
 128                <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>).</li>
 129           <li> The <em>filesystem</em> path to the directory containing the
 130                <code class="directive">RewriteRule</code>, suffixed by the relative
 131                substitution is also valid as a URL path on the server
 132                (this is rare).</li>
 133       </ul>
 134
 135 <p> In the example below, <code class="directive">RewriteBase</code> is necessary
 136     to avoid rewriting to http://example.com/opt/myapp-1.2.3/welcome.html
 137     since the resource was not relative to the document root.  This
 138     misconfiguration would normally cause the server to look for an "opt"
 139     directory under the document root.</p>
 140 <pre class="prettyprint lang-config">DocumentRoot /var/www/example.com
 141 Alias /myapp /opt/myapp-1.2.3
 142 &lt;Directory /opt/myapp-1.2.3&gt;
 143     RewriteEngine On
 144     RewriteBase /myapp/
 145     RewriteRule ^index\.html$  welcome.html
 146 &lt;/Directory&gt;</pre>
 147
 148
 149 </div>
 150 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 151 <div class="directive-section"><h2><a name="RewriteCond" id="RewriteCond">RewriteCond</a> <a name="rewritecond" id="rewritecond">Directive</a></h2>
 152 <table class="directive">
 153 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a condition under which rewriting will take place
 154 </td></tr>
 155 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> RewriteCond
 156       <em>TestString</em> <em>CondPattern</em></code></td></tr>
 157 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 158 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 159 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 160 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 161 </table>
 162       <p>The <code class="directive">RewriteCond</code> directive defines a
 163       rule condition. One or more <code class="directive">RewriteCond</code>
 164       can precede a <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
 165       directive. The following rule is then only used if both
 166       the current state of the URI matches its pattern, <strong>and</strong> if these conditions are met.</p>
 167
 168       <p><em>TestString</em> is a string which can contain the
 169       following expanded constructs in addition to plain text:</p>
 170
 171       <ul>
 172         <li>
 173           <strong>RewriteRule backreferences</strong>: These are
 174           backreferences of the form <strong><code>$N</code></strong>
 175           (0 &lt;= N &lt;= 9). $1 to $9 provide access to the grouped
 176           parts (in parentheses) of the pattern, from the
 177           <code>RewriteRule</code> which is subject to the current
 178           set of <code>RewriteCond</code> conditions. $0 provides
 179           access to the whole string matched by that pattern.
 180         </li>
 181         <li>
 182           <strong>RewriteCond backreferences</strong>: These are
 183           backreferences of the form <strong><code>%N</code></strong>
 184           (0 &lt;= N &lt;= 9). %1 to %9 provide access to the grouped
 185           parts (again, in parentheses) of the pattern, from the last matched
 186           <code>RewriteCond</code> in the current set
 187           of conditions. %0 provides access to the whole string matched by
 188           that pattern.
 189         </li>
 190         <li>
 191           <strong>RewriteMap expansions</strong>: These are
 192           expansions of the form <strong><code>${mapname:key|default}</code></strong>.
 193           See <a href="#mapfunc">the documentation for
 194           RewriteMap</a> for more details.
 195         </li>
 196         <li>
 197           <strong>Server-Variables</strong>: These are variables of
 198           the form
 199             <strong><code>%{</code> <em>NAME_OF_VARIABLE</em>
 200             <code>}</code></strong>
 201           where <em>NAME_OF_VARIABLE</em> can be a string taken
 202           from the following list:
 203
 204           <table>
 205
 206             <tr>
 207               <th>HTTP headers:</th> <th>connection &amp; request:</th> <th />
 208             </tr>
 209
 210             <tr>
 211               <td>
 212                  HTTP_USER_AGENT<br />
 213                  HTTP_REFERER<br />
 214                  HTTP_COOKIE<br />
 215                  HTTP_FORWARDED<br />
 216                  HTTP_HOST<br />
 217                  HTTP_PROXY_CONNECTION<br />
 218                  HTTP_ACCEPT<br />
 219               </td>
 220
 221               <td>
 222                  REMOTE_ADDR<br />
 223                  CONN_REMOTE_ADDR<br />
 224                  REMOTE_HOST<br />
 225                  REMOTE_PORT<br />
 226                  REMOTE_USER<br />
 227                  REMOTE_IDENT<br />
 228                  REQUEST_METHOD<br />
 229                  SCRIPT_FILENAME<br />
 230                  PATH_INFO<br />
 231                  QUERY_STRING<br />
 232                  AUTH_TYPE<br />
 233               </td>
 234
 235               <td />
 236             </tr>
 237
 238             <tr>
 239               <th>server internals:</th> <th>date and time:</th> <th>specials:</th>
 240             </tr>
 241
 242             <tr>
 243               <td>
 244                  DOCUMENT_ROOT<br />
 245                  SERVER_ADMIN<br />
 246                  SERVER_NAME<br />
 247                  SERVER_ADDR<br />
 248                  SERVER_PORT<br />
 249                  SERVER_PROTOCOL<br />
 250                  SERVER_SOFTWARE<br />
 251               </td>
 252
 253               <td>
 254                  TIME_YEAR<br />
 255                  TIME_MON<br />
 256                  TIME_DAY<br />
 257                  TIME_HOUR<br />
 258                  TIME_MIN<br />
 259                  TIME_SEC<br />
 260                  TIME_WDAY<br />
 261                  TIME<br />
 262               </td>
 263
 264               <td>
 265                  API_VERSION<br />
 266                  THE_REQUEST<br />
 267                  REQUEST_URI<br />
 268                  REQUEST_FILENAME<br />
 269                  IS_SUBREQ<br />
 270                  HTTPS<br />
 271                  REQUEST_SCHEME<br />
 272               </td>
 273             </tr>
 274           </table>
 275
 276                 <p>These variables all
 277                 correspond to the similarly named HTTP
 278                 MIME-headers, C variables of the Apache HTTP Server or
 279                 <code>struct tm</code> fields of the Unix system.
 280                 Most are documented elsewhere in the Manual or in
 281                 the CGI specification.</p>
 282
 283                 <p>SERVER_NAME and SERVER_PORT depend on the values of
 284                 <code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code> and
 285                 <code class="directive"><a href="../mod/core.html#usecanonicalphysicalport">UseCanonicalPhysicalPort</a></code>
 286                 respectively.</p>
 287
 288                 <p>Those that are special to mod_rewrite include those below.</p>
 289         <div class="note">
 290                 <dl>
 291                   <dt><code>IS_SUBREQ</code></dt>
 292
 293                   <dd>Will contain the text "true" if the request
 294                   currently being processed is a sub-request,
 295                   "false" otherwise. Sub-requests may be generated
 296                   by modules that need to resolve additional files
 297                   or URIs in order to complete their tasks.</dd>
 298
 299                   <dt><code>API_VERSION</code></dt>
 300
 301                   <dd>This is the version of the Apache httpd module API
 302                   (the internal interface between server and
 303                   module) in the current httpd build, as defined in
 304                   include/ap_mmn.h. The module API version
 305                   corresponds to the version of Apache httpd in use (in
 306                   the release version of Apache httpd 1.3.14, for
 307                   instance, it is 19990320:10), but is mainly of
 308                   interest to module authors.</dd>
 309
 310                   <dt><code>THE_REQUEST</code></dt>
 311
 312                   <dd>The full HTTP request line sent by the
 313                   browser to the server (e.g., "<code>GET
 314                   /index.html HTTP/1.1</code>"). This does not
 315                   include any additional headers sent by the
 316                   browser.  This value has not been unescaped
 317                   (decoded), unlike most other variables below.</dd>
 318
 319                   <dt><code>REQUEST_URI</code></dt>
 320
 321                   <dd>The path component of the requested URI,
 322                   such as "/index.html".  This notably excludes the
 323                   query string which is available as as its own variable
 324                   named <code>QUERY_STRING</code>.</dd>
 325
 326                   <dt><code>REQUEST_FILENAME</code></dt>
 327
 328                   <dd>The full local filesystem path to the file or
 329                   script matching the request, if this has already
 330                   been determined by the server at the time
 331                   <code>REQUEST_FILENAME</code> is referenced. Otherwise,
 332                   such as when used in virtual host context, the same
 333                   value as <code>REQUEST_URI</code>.  Depending on the value of
 334                   <code class="directive"><a href="../mod/core.html#acceptpathinfo">AcceptPathInfo</a></code>, the
 335                   server may have only used some leading components of the
 336                   <code>REQUEST_URI</code> to map the request to a file.
 337                   </dd>
 338
 339                   <dt><code>HTTPS</code></dt>
 340
 341                   <dd>Will contain the text "on" if the connection is
 342                   using SSL/TLS, or "off" otherwise.  (This variable
 343                   can be safely used regardless of whether or not
 344                   <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is loaded).</dd>
 345
 346                   <dt><code>REQUEST_SCHEME</code></dt>
 347
 348                   <dd>Will contain the scheme of the request (usually
 349                   "http" or "https"). This value can be influenced with
 350                   <code class="directive"><a href="../mod/core.html#servername">ServerName</a></code>.</dd>
 351
 352                   <dt><code>REMOTE_ADDR</code></dt>
 353                   <dd>The IP address of the remote host (see the
 354                   <code class="module"><a href="../mod/mod_remoteip.html">mod_remoteip</a></code> module).</dd>
 355
 356                   <dt><code>CONN_REMOTE_ADDR</code></dt>
 357                   <dd>Since 2.4.8: The peer IP address of the connection (see the
 358                   <code class="module"><a href="../mod/mod_remoteip.html">mod_remoteip</a></code> module).</dd>
 359
 360                 </dl>
 361 </div>
 362         </li>
 363       </ul>
 364
 365       <p>If the <em>TestString</em> has the special value <code>expr</code>,
 366       the <em>CondPattern</em> will be treated as an
 367       <a href="../expr.html">ap_expr</a>. HTTP headers referenced in the
 368       expression will be added to the Vary header if the <code>novary</code>
 369       flag is not given.</p>
 370
 371       <p>Other things you should be aware of:</p>
 372
 373       <ol>
 374         <li>
 375         <p>The variables SCRIPT_FILENAME and REQUEST_FILENAME
 376         contain the same value - the value of the
 377         <code>filename</code> field of the internal
 378         <code>request_rec</code> structure of the Apache HTTP Server.
 379         The first name is the commonly known CGI variable name
 380         while the second is the appropriate counterpart of
 381         REQUEST_URI (which contains the value of the
 382         <code>uri</code> field of <code>request_rec</code>).</p>
 383         <p>If a substitution occurred and the rewriting continues,
 384         the value of both variables will be updated accordingly.</p>
 385         <p>If used in per-server context (<em>i.e.</em>, before the
 386         request is mapped to the filesystem) SCRIPT_FILENAME and
 387         REQUEST_FILENAME cannot contain the full local filesystem
 388         path since the path is unknown at this stage of processing.
 389         Both variables will initially contain the value of REQUEST_URI
 390         in that case. In order to obtain the full local filesystem
 391         path of the request in per-server context, use an URL-based
 392         look-ahead <code>%{LA-U:REQUEST_FILENAME}</code> to determine
 393         the final value of REQUEST_FILENAME.</p></li>
 394
 395         <li>
 396         <code>%{ENV:variable}</code>, where <em>variable</em> can be
 397         any environment variable, is also available.
 398         This is looked-up via internal
 399         Apache httpd structures and (if not found there) via
 400         <code>getenv()</code> from the Apache httpd server process.</li>
 401
 402         <li>
 403         <code>%{SSL:variable}</code>, where <em>variable</em> is the
 404         name of an <a href="mod_ssl.html#envvars">SSL environment
 405         variable</a>, can be used whether or not
 406         <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is loaded, but will always expand to
 407         the empty string if it is not.  Example:
 408         <code>%{SSL:SSL_CIPHER_USEKEYSIZE}</code> may expand to
 409         <code>128</code>.</li>
 410
 411         <li>
 412         <code>%{HTTP:header}</code>, where <em>header</em> can be
 413         any HTTP MIME-header name, can always be used to obtain the
 414         value of a header sent in the HTTP request.
 415         Example: <code>%{HTTP:Proxy-Connection}</code> is
 416         the value of the HTTP header
 417         ``<code>Proxy-Connection:</code>''.
 418         <p>If a HTTP header is used in a condition this header is added to
 419         the Vary header of the response in case the condition evaluates to
 420         to true for the request. It is <strong>not</strong> added if the
 421         condition evaluates to false for the request. Adding the HTTP header
 422         to the Vary header of the response is needed for proper caching.</p>
 423         <p>It has to be kept in mind that conditions follow a short circuit
 424         logic in the case of the '<strong><code>ornext|OR</code></strong>' flag
 425         so that certain conditions might not be evaluated at all.</p></li>
 426
 427         <li>
 428         <a id="LA-U" name="LA-U"><code>%{LA-U:variable}</code></a>
 429         can be used for look-aheads which perform
 430         an internal (URL-based) sub-request to determine the final
 431         value of <em>variable</em>. This can be used to access
 432         variable for rewriting which is not available at the current
 433         stage, but will be set in a later phase.
 434         <p>For instance, to rewrite according to the
 435         <code>REMOTE_USER</code> variable from within the
 436         per-server context (<code>httpd.conf</code> file) you must
 437         use <code>%{LA-U:REMOTE_USER}</code> - this
 438         variable is set by the authorization phases, which come
 439         <em>after</em> the URL translation phase (during which mod_rewrite
 440         operates).</p>
 441         <p>On the other hand, because mod_rewrite implements
 442         its per-directory context (<code>.htaccess</code> file) via
 443         the Fixup phase of the API and because the authorization
 444         phases come <em>before</em> this phase, you just can use
 445         <code>%{REMOTE_USER}</code> in that context.</p></li>
 446
 447         <li>
 448         <code>%{LA-F:variable}</code> can be used to perform an internal
 449         (filename-based) sub-request, to determine the final value
 450         of <em>variable</em>. Most of the time, this is the same as
 451         LA-U above.</li>
 452       </ol>
 453
 454       <p><em>CondPattern</em> is the condition pattern,
 455        a regular expression which is applied to the
 456       current instance of the <em>TestString</em>.
 457       <em>TestString</em> is first evaluated, before being matched against
 458       <em>CondPattern</em>.</p>
 459
 460       <p><em>CondPattern</em> is usually a
 461       <em>perl compatible regular expression</em>, but there is
 462       additional syntax available to perform other useful tests against
 463       the <em>Teststring</em>:</p>
 464
 465       <ol>
 466         <li>You can prefix the pattern string with a
 467         '<code>!</code>' character (exclamation mark) to specify a
 468         <strong>non</strong>-matching pattern.</li>
 469
 470         <li>
 471           You can perform lexicographical string comparisons:
 472
 473           <ul>
 474             <li>'<strong>&lt;CondPattern</strong>' (lexicographically
 475             precedes)<br />
 476             Treats the <em>CondPattern</em> as a plain string and
 477             compares it lexicographically to <em>TestString</em>. True if
 478             <em>TestString</em> lexicographically precedes
 479             <em>CondPattern</em>.</li>
 480
 481             <li>'<strong>&gt;CondPattern</strong>' (lexicographically
 482             follows)<br />
 483             Treats the <em>CondPattern</em> as a plain string and
 484             compares it lexicographically to <em>TestString</em>. True if
 485             <em>TestString</em> lexicographically follows
 486             <em>CondPattern</em>.</li>
 487
 488             <li>'<strong>=CondPattern</strong>' (lexicographically
 489             equal)<br />
 490             Treats the <em>CondPattern</em> as a plain string and
 491             compares it lexicographically to <em>TestString</em>. True if
 492             <em>TestString</em> is lexicographically equal to
 493             <em>CondPattern</em> (the two strings are exactly
 494             equal, character for character). If <em>CondPattern</em>
 495             is <code>""</code> (two quotation marks) this
 496             compares <em>TestString</em> to the empty string.</li>
 497
 498             <li>'<strong>&lt;=CondPattern</strong>' (lexicographically
 499             less than or equal to)<br />
 500             Treats the <em>CondPattern</em> as a plain string and
 501             compares it lexicographically to <em>TestString</em>. True
 502             if <em>TestString</em> lexicographically precedes
 503             <em>CondPattern</em>, or is equal to <em>CondPattern</em>
 504             (the two strings are equal, character for character).</li>
 505
 506             <li>'<strong>&gt;=CondPattern</strong>' (lexicographically
 507             greater than or equal to)<br />
 508             Treats the <em>CondPattern</em> as a plain string and
 509             compares it lexicographically to <em>TestString</em>. True
 510             if <em>TestString</em> lexicographically follows
 511             <em>CondPattern</em>, or is equal to <em>CondPattern</em>
 512             (the two strings are equal, character for character).</li>
 513         </ul></li>
 514
 515         <li>
 516           You can perform integer comparisons:
 517           <ul>
 518
 519             <li>'<strong>-eq</strong>' (is numerically
 520             <strong>eq</strong>ual to)<br />
 521             The <em>TestString</em> is treated as an integer, and is
 522             numerically compared to the <em>CondPattern</em>. True if
 523             the two are numerically equal.</li>
 524
 525             <li>'<strong>-ge</strong>' (is numerically
 526             <strong>g</strong>reater than or <strong>e</strong>qual to)<br />
 527             The <em>TestString</em> is treated as an integer, and is
 528             numerically compared to the <em>CondPattern</em>. True if
 529             the <em>TestString</em> is numerically greater than or equal
 530             to the <em>CondPattern</em>.</li>
 531
 532              <li>'<strong>-gt</strong>' (is numerically
 533             <strong>g</strong>reater <strong>t</strong>han)<br />
 534             The <em>TestString</em> is treated as an integer, and is
 535             numerically compared to the <em>CondPattern</em>. True if
 536             the <em>TestString</em> is numerically greater than
 537             the <em>CondPattern</em>.</li>
 538
 539             <li>'<strong>-le</strong>' (is numerically
 540             <strong>l</strong>ess than or <strong>e</strong>qual to)<br />
 541             The <em>TestString</em> is treated as an integer, and is
 542             numerically compared to the <em>CondPattern</em>. True if
 543             the <em>TestString</em> is numerically less than or equal
 544             to the <em>CondPattern</em>. Avoid confusion with the
 545             <strong>-l</strong> by using the <strong>-L</strong> or
 546             <strong>-h</strong> variant.</li>
 547
 548              <li>'<strong>-lt</strong>' (is numerically
 549             <strong>l</strong>ess <strong>t</strong>han)<br />
 550             The <em>TestString</em> is treated as an integer, and is
 551             numerically compared to the <em>CondPattern</em>. True if
 552             the <em>TestString</em> is numerically less than
 553             the <em>CondPattern</em>. Avoid confusion with the
 554             <strong>-l</strong> by using the <strong>-L</strong> or
 555             <strong>-h</strong> variant.</li>
 556
 557            </ul>
 558         </li>
 559
 560         <li>You can perform various file attribute tests:
 561           <ul>
 562             <li>'<strong>-d</strong>' (is
 563             <strong>d</strong>irectory)<br />
 564              Treats the <em>TestString</em> as a pathname and tests
 565             whether or not it exists, and is a directory.</li>
 566
 567             <li>'<strong>-f</strong>' (is regular
 568             <strong>f</strong>ile)<br />
 569              Treats the <em>TestString</em> as a pathname and tests
 570             whether or not it exists, and is a regular file.</li>
 571
 572             <li>'<strong>-F</strong>' (is existing file, via
 573             subrequest)<br />
 574             Checks whether or not <em>TestString</em> is a valid file,
 575             accessible via all the server's currently-configured
 576             access controls for that path. This uses an internal
 577             subrequest to do the check, so use it with care -
 578             it can impact your server's performance!</li>
 579
 580             <li>'<strong>-H</strong>' (is symbolic link, bash convention)<br />
 581             See <strong>-l</strong>.</li>
 582
 583             <li>'<strong>-l</strong>' (is symbolic
 584             <strong>l</strong>ink)<br />
 585             Treats the <em>TestString</em> as a pathname and tests
 586             whether or not it exists, and is a symbolic link. May also
 587             use the bash convention of <strong>-L</strong> or
 588             <strong>-h</strong> if there's a possibility of confusion
 589             such as when using the <strong>-lt</strong> or
 590             <strong>-le</strong> tests.</li>
 591
 592             <li>'<strong>-L</strong>' (is symbolic link, bash convention)<br />
 593             See <strong>-l</strong>.</li>
 594
 595             <li>'<strong>-s</strong>' (is regular file, with
 596             <strong>s</strong>ize)<br />
 597             Treats the <em>TestString</em> as a pathname and tests
 598             whether or not it exists, and is a regular file with size greater
 599             than zero.</li>
 600
 601             <li><p>'<strong>-U</strong>' (is existing URL, via
 602             subrequest)<br />
 603             Checks whether or not <em>TestString</em> is a valid URL,
 604             accessible via all the server's currently-configured
 605             access controls for that path. This uses an internal
 606             subrequest to do the check, so use it with care -
 607             it can impact your server's performance!</p>
 608             <p> This flag <em>only</em> returns information about things
 609             like access control, authentication, and authorization.  This flag
 610             <em>does not</em> return information about the status code the
 611             configured handler (static file, CGI, proxy, etc.) would have
 612             returned.</p> </li>
 613
 614             <li>'<strong>-x</strong>' (has e<strong>x</strong>ecutable
 615             permissions)<br />
 616             Treats the <em>TestString</em> as a pathname and tests
 617             whether or not it exists, and has executable permissions.
 618             These permissions are determined according to
 619             the underlying OS.</li>
 620
 621           </ul>
 622
 623 <div class="note"><h3>Note:</h3>
 624               All of these tests can
 625               also be prefixed by an exclamation mark ('!') to
 626               negate their meaning.
 627 </div>
 628         </li>
 629
 630         <li>
 631            <p>If the <em>TestString</em> has the special value <code>expr</code>, the
 632            <em>CondPattern</em> will be treated as an
 633            <a href="../expr.html">ap_expr</a>.</p>
 634
 635            <p>
 636             In the below example, <code>-strmatch</code> is used to
 637             compare the <code>REFERER</code> against the site hostname,
 638             to block unwanted hotlinking.
 639            </p>
 640
 641            <pre class="prettyprint lang-config">           RewriteCond expr "! %{HTTP_REFERER} -strmatch '*://%{HTTP_HOST}/*'"<br />
 642            RewriteRule ^/images - [F]</pre>
 643
 644         </li>
 645
 646         <li>You can also set special flags for
 647       <em>CondPattern</em> by appending
 648         <strong><code>[</code><em>flags</em><code>]</code></strong>
 649       as the third argument to the <code>RewriteCond</code>
 650       directive, where <em>flags</em> is a comma-separated list of any of the
 651       following flags:
 652
 653       <ul>
 654         <li>'<strong><code>nocase|NC</code></strong>'
 655         (<strong>n</strong>o <strong>c</strong>ase)<br />
 656         This makes the test case-insensitive - differences
 657         between 'A-Z' and 'a-z' are ignored, both in the
 658         expanded <em>TestString</em> and the <em>CondPattern</em>.
 659         This flag is effective only for comparisons between
 660         <em>TestString</em> and <em>CondPattern</em>. It has no
 661         effect on filesystem and subrequest checks.</li>
 662
 663         <li>
 664           '<strong><code>ornext|OR</code></strong>'
 665           (<strong>or</strong> next condition)<br />
 666           Use this to combine rule conditions with a local OR
 667           instead of the implicit AND. Typical example:
 668
 669 <pre class="prettyprint lang-config">RewriteCond %{REMOTE_HOST}  ^host1  [OR]
 670 RewriteCond %{REMOTE_HOST}  ^host2  [OR]
 671 RewriteCond %{REMOTE_HOST}  ^host3
 672 RewriteRule ...some special stuff for any of these hosts...</pre>
 673
 674
 675           Without this flag you would have to write the condition/rule
 676           pair three times.
 677         </li>
 678
 679         <li>'<strong><code>novary|NV</code></strong>'
 680         (<strong>n</strong>o <strong>v</strong>ary)<br />
 681         If a HTTP header is used in the condition, this flag prevents
 682         this header from being added to the Vary header of the response. <br />
 683         Using this flag might break proper caching of the response if
 684         the representation of this response varies on the value of this header.
 685         So this flag should be only used if the meaning of the Vary header
 686         is well understood.
 687         </li>
 688       </ul>
 689       </li>
 690      </ol>
 691
 692       <p><strong>Example:</strong></p>
 693
 694        <p>To rewrite the Homepage of a site according to the
 695         ``<code>User-Agent:</code>'' header of the request, you can
 696         use the following: </p>
 697
 698 <pre class="prettyprint lang-config">RewriteCond  %{HTTP_USER_AGENT}  (iPhone|Blackberry|Android)
 699 RewriteRule  ^/$                 /homepage.mobile.html  [L]
 700
 701 RewriteRule  ^/$                 /homepage.std.html  [L]</pre>
 702
 703
 704         <p>Explanation: If you use a browser which identifies itself
 705         as a mobile browser (note that the example is incomplete, as
 706         there are many other mobile platforms), the mobile version of
 707         the homepage is served. Otherwise, the standard page is served.
 708         </p>
 709
 710
 711 </div>
 712 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 713 <div class="directive-section"><h2><a name="RewriteEngine" id="RewriteEngine">RewriteEngine</a> <a name="rewriteengine" id="rewriteengine">Directive</a></h2>
 714 <table class="directive">
 715 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables or disables runtime rewriting engine</td></tr>
 716 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteEngine on|off</code></td></tr>
 717 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteEngine off</code></td></tr>
 718 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 719 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 720 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 721 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 722 </table>
 723
 724       <p>The <code class="directive">RewriteEngine</code> directive enables or
 725       disables the runtime rewriting engine. If it is set to
 726       <code>off</code> this module does no runtime processing at
 727       all. It does not even update the <code>SCRIPT_URx</code>
 728       environment variables.</p>
 729
 730       <p>Use this directive to disable rules in a particular contact,
 731       rather than commenting out all the <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives.</p>
 732
 733       <p>Note that rewrite configurations are not
 734       inherited by virtual hosts. This means that you need to have a
 735       <code>RewriteEngine on</code> directive for each virtual host
 736       in which you wish to use rewrite rules.</p>
 737
 738       <p><code class="directive">RewriteMap</code> directives of the type <code>prg</code>
 739       are not started during server initialization if they're defined in a
 740       context that does not have <code class="directive">RewriteEngine</code>  set to
 741       <code>on</code></p>
 742
 743 </div>
 744 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 745 <div class="directive-section"><h2><a name="RewriteMap" id="RewriteMap">RewriteMap</a> <a name="rewritemap" id="rewritemap">Directive</a></h2>
 746 <table class="directive">
 747 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a mapping function for key-lookup</td></tr>
 748 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
 749 </code></td></tr>
 750 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 751 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 752 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
 753 </table>
 754       <p>The <code class="directive">RewriteMap</code> directive defines a
 755       <em>Rewriting Map</em> which can be used inside rule
 756       substitution strings by the mapping-functions to
 757       insert/substitute fields through a key lookup. The source of
 758       this lookup can be of various types.</p>
 759
 760       <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
 761       the name of the map and will be used to specify a
 762       mapping-function for the substitution strings of a rewriting
 763       rule via one of the following constructs:</p>
 764
 765       <p class="indent">
 766         <strong><code>${</code> <em>MapName</em> <code>:</code>
 767         <em>LookupKey</em> <code>}</code><br />
 768          <code>${</code> <em>MapName</em> <code>:</code>
 769         <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
 770         <code>}</code></strong>
 771       </p>
 772
 773       <p>When such a construct occurs, the map <em>MapName</em> is
 774       consulted and the key <em>LookupKey</em> is looked-up. If the
 775       key is found, the map-function construct is substituted by
 776       <em>SubstValue</em>. If the key is not found then it is
 777       substituted by <em>DefaultValue</em> or by the empty string
 778       if no <em>DefaultValue</em> was specified. Empty values
 779       behave as if the key was absent, therefore it is not possible
 780       to distinguish between empty-valued keys and absent keys.</p>
 781
 782       <p>For example, you might define a
 783       <code class="directive">RewriteMap</code> as:</p>
 784
 785       <pre class="prettyprint lang-config">      RewriteMap examplemap txt:/path/to/file/map.txt</pre>
 786
 787
 788       <p>You would then be able to use this map in a
 789       <code class="directive">RewriteRule</code> as follows:</p>
 790
 791       <pre class="prettyprint lang-config">      RewriteRule ^/ex/(.*) ${examplemap:$1}</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 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>
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>