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