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