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