granicus.if.org Git - apache/blob - docs/manual/mod/mod_rewrite.html.en

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