1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 5<!--%hypertext --> 6<!-- mod_rewrite.html --> 7<!-- Documentation for the mod_rewrite Apache module --> 8 9<html xmlns="http://www.w3.org/1999/xhtml"> 10 <head> 11 <meta name="generator" content="HTML Tidy, see www.w3.org" /> 12 13 <title>Apache module mod_rewrite</title> 14 </head> 15 <!-- Background white, links blue (unvisited), navy (visited), red (active) --> 16 17 <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" 18 vlink="#000080" alink="#FF0000"> 19 <blockquote> 20 <!-- page indentation --> 21 <div align="CENTER"> 22 <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> 23 24 <h3>Apache HTTP Server Version 1.3</h3> 25 </div> 26 27 <br /> 28 29 30 <h1 align="CENTER">Module mod_rewrite<br /> 31 URL Rewriting Engine</h1> 32 33 <p>This module provides a rule-based rewriting engine to 34 rewrite requested URLs on the fly.</p> 35 36 <p><a href="module-dict.html#Status" 37 rel="Help"><strong>Status:</strong></a> Extension<br /> 38 <a href="module-dict.html#SourceFile" 39 rel="Help"><strong>Source File:</strong></a> 40 mod_rewrite.c<br /> 41 <a href="module-dict.html#ModuleIdentifier" 42 rel="Help"><strong>Module Identifier:</strong></a> 43 rewrite_module<br /> 44 <a href="module-dict.html#Compatibility" 45 rel="Help"><strong>Compatibility:</strong></a> Available in 46 Apache 1.2 and later.</p> 47 <hr noshade="noshade" size="1" /> 48 <br /> 49 50 51 <h2>Summary</h2> 52 53 <blockquote> 54 <blockquote> 55 <blockquote> 56 <em>``The great thing about mod_rewrite is it gives you 57 all the configurability and flexibility of Sendmail. 58 The downside to mod_rewrite is that it gives you all 59 the configurability and flexibility of Sendmail.''</em> 60 61 62 <div align="RIGHT"> 63 -- Brian Behlendorf<br /> 64 Apache Group 65 </div> 66 </blockquote> 67 </blockquote> 68 </blockquote> 69 70 <blockquote> 71 <blockquote> 72 <blockquote> 73 <em>`` Despite the tons of examples and docs, 74 mod_rewrite is voodoo. Damned cool voodoo, but still 75 voodoo. ''</em> 76 77 <div align="RIGHT"> 78 -- Brian Moore<br /> 79 bem@news.cmc.net 80 </div> 81 </blockquote> 82 </blockquote> 83 </blockquote> 84 Welcome to mod_rewrite, the Swiss Army Knife of URL 85 manipulation! 86 87 <p>This module uses a rule-based rewriting engine (based on a 88 regular-expression parser) to rewrite requested URLs on the 89 fly. It supports an unlimited number of rules and an 90 unlimited number of attached rule conditions for each rule to 91 provide a really flexible and powerful URL manipulation 92 mechanism. The URL manipulations can depend on various tests, 93 for instance server variables, environment variables, HTTP 94 headers, time stamps and even external database lookups in 95 various formats can be used to achieve a really granular URL 96 matching.</p> 97 98 <p>This module operates on the full URLs (including the 99 path-info part) both in per-server context 100 (<code>httpd.conf</code>) and per-directory context 101 (<code>.htaccess</code>) and can even generate query-string 102 parts on result. The rewritten result can lead to internal 103 sub-processing, external request redirection or even to an 104 internal proxy throughput.</p> 105 106 <p>But all this functionality and flexibility has its 107 drawback: complexity. So don't expect to understand this 108 entire module in just one day.</p> 109 110 <p>This module was invented and originally written in April 111 1996<br /> 112 and gifted exclusively to the The Apache Group in July 1997 113 by</p> 114 115 <blockquote> 116 <a href="http://www.engelschall.com/"><code>Ralf S. 117 Engelschall</code></a><br /> 118 <a 119 href="mailto:rse@engelschall.com"><code>rse@engelschall.com</code></a><br /> 120 <a 121 href="http://www.engelschall.com/"><code>www.engelschall.com</code></a> 122 </blockquote> 123 <hr noshade="noshade" size="1" /> 124 125 <h2>Table Of Contents</h2> 126 127 <p><strong>Internal Processing</strong></p> 128 129 <ul> 130 <li><a href="#InternalAPI">API Phases</a></li> 131 132 <li><a href="#InternalRuleset">Ruleset Processing</a></li> 133 134 <li><a href="#InternalBackRefs">Regex Back-Reference 135 Availability</a></li> 136 </ul> 137 138 <p><strong>Configuration Directives</strong></p> 139 140 <ul> 141 <li><a href="#RewriteEngine">RewriteEngine</a></li> 142 143 <li><a href="#RewriteOptions">RewriteOptions</a></li> 144 145 <li><a href="#RewriteLog">RewriteLog</a></li> 146 147 <li><a href="#RewriteLogLevel">RewriteLogLevel</a></li> 148 149 <li><a href="#RewriteLock">RewriteLock</a></li> 150 151 <li><a href="#RewriteMap">RewriteMap</a></li> 152 153 <li><a href="#RewriteBase">RewriteBase</a></li> 154 155 <li><a href="#RewriteCond">RewriteCond</a></li> 156 157 <li><a href="#RewriteRule">RewriteRule</a></li> 158 </ul> 159 <strong>Miscellaneous</strong> 160 161 <ul> 162 <li><a href="#EnvVar">Environment Variables</a></li> 163 164 <li><a href="#Solutions">Practical Solutions</a></li> 165 </ul> 166 <hr noshade="noshade" size="1" /> 167 168 <center> 169 <h1><a id="Internal" name="Internal">Internal 170 Processing</a></h1> 171 </center> 172 <hr noshade="noshade" size="1" /> 173 174 <p>The internal processing of this module is very complex but 175 needs to be explained once even to the average user to avoid 176 common mistakes and to let you exploit its full 177 functionality.</p> 178 179 <h2><a id="InternalAPI" name="InternalAPI">API 180 Phases</a></h2> 181 182 <p>First you have to understand that when Apache processes a 183 HTTP request it does this in phases. A hook for each of these 184 phases is provided by the Apache API. Mod_rewrite uses two of 185 these hooks: the URL-to-filename translation hook which is 186 used after the HTTP request has been read but before any 187 authorization starts and the Fixup hook which is triggered 188 after the authorization phases and after the per-directory 189 config files (<code>.htaccess</code>) have been read, but 190 before the content handler is activated.</p> 191 192 <p>So, after a request comes in and Apache has determined the 193 corresponding server (or virtual server) the rewriting engine 194 starts processing of all mod_rewrite directives from the 195 per-server configuration in the URL-to-filename phase. A few 196 steps later when the final data directories are found, the 197 per-directory configuration directives of mod_rewrite are 198 triggered in the Fixup phase. In both situations mod_rewrite 199 rewrites URLs either to new URLs or to filenames, although 200 there is no obvious distinction between them. This is a usage 201 of the API which was not intended to be this way when the API 202 was designed, but as of Apache 1.x this is the only way 203 mod_rewrite can operate. To make this point more clear 204 remember the following two points:</p> 205 206 <ol> 207 <li>Although mod_rewrite rewrites URLs to URLs, URLs to 208 filenames and even filenames to filenames, the API 209 currently provides only a URL-to-filename hook. In Apache 210 2.0 the two missing hooks will be added to make the 211 processing more clear. But this point has no drawbacks for 212 the user, it is just a fact which should be remembered: 213 Apache does more in the URL-to-filename hook than the API 214 intends for it.</li> 215 216 <li> 217 Unbelievably mod_rewrite provides URL manipulations in 218 per-directory context, <em>i.e.</em>, within 219 <code>.htaccess</code> files, although these are reached 220 a very long time after the URLs have been translated to 221 filenames. It has to be this way because 222 <code>.htaccess</code> files live in the filesystem, so 223 processing has already reached this stage. In other 224 words: According to the API phases at this time it is too 225 late for any URL manipulations. To overcome this chicken 226 and egg problem mod_rewrite uses a trick: When you 227 manipulate a URL/filename in per-directory context 228 mod_rewrite first rewrites the filename back to its 229 corresponding URL (which is usually impossible, but see 230 the <code>RewriteBase</code> directive below for the 231 trick to achieve this) and then initiates a new internal 232 sub-request with the new URL. This restarts processing of 233 the API phases. 234 235 <p>Again mod_rewrite tries hard to make this complicated 236 step totally transparent to the user, but you should 237 remember here: While URL manipulations in per-server 238 context are really fast and efficient, per-directory 239 rewrites are slow and inefficient due to this chicken and 240 egg problem. But on the other hand this is the only way 241 mod_rewrite can provide (locally restricted) URL 242 manipulations to the average user.</p> 243 </li> 244 </ol> 245 246 <p>Don't forget these two points!</p> 247 248 <h2><a id="InternalRuleset" name="InternalRuleset">Ruleset 249 Processing</a></h2> 250 Now when mod_rewrite is triggered in these two API phases, it 251 reads the configured rulesets from its configuration 252 structure (which itself was either created on startup for 253 per-server context or during the directory walk of the Apache 254 kernel for per-directory context). Then the URL rewriting 255 engine is started with the contained ruleset (one or more 256 rules together with their conditions). The operation of the 257 URL rewriting engine itself is exactly the same for both 258 configuration contexts. Only the final result processing is 259 different. 260 261 <p>The order of rules in the ruleset is important because the 262 rewriting engine processes them in a special (and not very 263 obvious) order. The rule is this: The rewriting engine loops 264 through the ruleset rule by rule (<code>RewriteRule</code> 265 directives) and when a particular rule matches it optionally 266 loops through existing corresponding conditions 267 (<code>RewriteCond</code> directives). For historical reasons 268 the conditions are given first, and so the control flow is a 269 little bit long-winded. See Figure 1 for more details.</p> 270 271 <div align="CENTER"> 272 <table cellspacing="0" cellpadding="2" border="0"> 273 <tr> 274 <td bgcolor="#CCCCCC"><img 275 src="../images/mod_rewrite_fig1.gif" width="428" 276 height="385" 277 alt="[Needs graphics capability to display]" /></td> 278 </tr> 279 280 <tr> 281 <td align="CENTER"><strong>Figure 1:</strong> The 282 control flow through the rewriting ruleset</td> 283 </tr> 284 </table> 285 </div> 286 287 <p>As you can see, first the URL is matched against the 288 <em>Pattern</em> of each rule. When it fails mod_rewrite 289 immediately stops processing this rule and continues with the 290 next rule. If the <em>Pattern</em> matches, mod_rewrite looks 291 for corresponding rule conditions. If none are present, it 292 just substitutes the URL with a new value which is 293 constructed from the string <em>Substitution</em> and goes on 294 with its rule-looping. But if conditions exist, it starts an 295 inner loop for processing them in the order that they are 296 listed. For conditions the logic is different: we don't match 297 a pattern against the current URL. Instead we first create a 298 string <em>TestString</em> by expanding variables, 299 back-references, map lookups, <em>etc.</em> and then we try 300 to match <em>CondPattern</em> against it. If the pattern 301 doesn't match, the complete set of conditions and the 302 corresponding rule fails. If the pattern matches, then the 303 next condition is processed until no more conditions are 304 available. If all conditions match, processing is continued 305 with the substitution of the URL with 306 <em>Substitution</em>.</p> 307 308 <h2><a id="quoting" name="quoting">Quoting Special 309 Characters</a></h2> 310 311 <p>As of Apache 1.3.20, special characters in 312 <i>TestString</i> and <i>Substitution</i> strings can be 313 escaped (that is, treated as normal characters without their 314 usual special meaning) by prefixing them with a slosh ('\') 315 character. In other words, you can include an actual 316 dollar-sign character in a <i>Substitution</i> string by 317 using '<code>\$</code>'; this keeps mod_rewrite from trying 318 to treat it as a backreference.</p> 319 320 <h2><a id="InternalBackRefs" name="InternalBackRefs">Regex 321 Back-Reference Availability</a></h2> 322 One important thing here has to be remembered: Whenever you 323 use parentheses in <em>Pattern</em> or in one of the 324 <em>CondPattern</em>, back-references are internally created 325 which can be used with the strings <code>$N</code> and 326 <code>%N</code> (see below). These are available for creating 327 the strings <em>Substitution</em> and <em>TestString</em>. 328 Figure 2 shows to which locations the back-references are 329 transfered for expansion. 330 331 <div align="CENTER"> 332 <table cellspacing="0" cellpadding="2" border="0"> 333 <tr> 334 <td bgcolor="#CCCCCC"><img 335 src="../images/mod_rewrite_fig2.gif" width="381" 336 height="179" 337 alt="[Needs graphics capability to display]" /></td> 338 </tr> 339 340 <tr> 341 <td align="CENTER"><strong>Figure 2:</strong> The 342 back-reference flow through a rule</td> 343 </tr> 344 </table> 345 </div> 346 347 <p>We know this was a crash course on mod_rewrite's internal 348 processing. But you will benefit from this knowledge when 349 reading the following documentation of the available 350 directives.</p> 351 <hr noshade="noshade" size="1" /> 352 353 <center> 354 <h1><a id="Configuration" 355 name="Configuration">Configuration Directives</a></h1> 356 </center> 357 <hr noshade="noshade" size="1" /> 358 359 <h3><a id="RewriteEngine" 360 name="RewriteEngine">RewriteEngine</a></h3> 361 <a href="directive-dict.html#Syntax" 362 rel="Help"><strong>Syntax:</strong></a> RewriteEngine 363 on|off<br /> 364 <a href="directive-dict.html#Default" 365 rel="Help"><strong>Default:</strong></a> <code>RewriteEngine 366 off</code><br /> 367 <a href="directive-dict.html#Context" 368 rel="Help"><strong>Context:</strong></a> server config, 369 virtual host, directory, .htaccess<br /> 370 <a href="directive-dict.html#Override" 371 rel="Help"><strong>Override:</strong></a> FileInfo<br /> 372 <a href="directive-dict.html#Status" 373 rel="Help"><strong>Status:</strong></a> Extension<br /> 374 <a href="directive-dict.html#Module" 375 rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> 376 <a href="directive-dict.html#Compatibility" 377 rel="Help"><strong>Compatibility:</strong></a> Apache 378 1.2<br /> 379 380 381 <p>The <code>RewriteEngine</code> directive enables or 382 disables the runtime rewriting engine. If it is set to 383 <code>off</code> this module does no runtime processing at 384 all. It does not even update the <code>SCRIPT_URx</code> 385 environment variables.</p> 386 387 <p>Use this directive to disable the module instead of 388 commenting out all the <code>RewriteRule</code> 389 directives!</p> 390 391 <p>Note that, by default, rewrite configurations are not 392 inherited. This means that you need to have a 393 <code>RewriteEngine on</code> directive for each virtual host 394 in which you wish to use it.</p> 395 <hr noshade="noshade" size="1" /> 396 397 <h3><a id="RewriteOptions" 398 name="RewriteOptions">RewriteOptions</a></h3> 399 <a href="directive-dict.html#Syntax" 400 rel="Help"><strong>Syntax:</strong></a> RewriteOptions 401 <em>Option</em><br /> 402 <a href="directive-dict.html#Default" 403 rel="Help"><strong>Default:</strong></a> <code>RewriteOptions 404 MaxRedirects=10</code><br /> 405 <a href="directive-dict.html#Context" 406 rel="Help"><strong>Context:</strong></a> server config, 407 virtual host, directory, .htaccess<br /> 408 <a href="directive-dict.html#Override" 409 rel="Help"><strong>Override:</strong></a> FileInfo<br /> 410 <a href="directive-dict.html#Status" 411 rel="Help"><strong>Status:</strong></a> Extension<br /> 412 <a href="directive-dict.html#Module" 413 rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> 414 <a href="directive-dict.html#Compatibility" 415 rel="Help"><strong>Compatibility:</strong></a> Apache 416 1.2; <code>MaxRedirects</code> is available in Apache 1.3.28 and 417 later<br /> 418 419 420 <p>The <code>RewriteOptions</code> directive sets some 421 special options for the current per-server or per-directory 422 configuration. The <em>Option</em> strings can be one of the 423 following:</p> 424 425 <dl> 426 <dt><code>inherit</code></dt> 427 <dd>This forces the current configuration to inherit the 428 configuration of the parent. In per-virtual-server context 429 this means that the maps, conditions and rules of the main 430 server are inherited. In per-directory context this means 431 that conditions and rules of the parent directory's 432 <code>.htaccess</code> configuration are inherited.</dd> 433 434 <dt><code>MaxRedirects=<var>number</var></code></dt> 435 <dd>In order to prevent endless loops of internal redirects 436 issued by per-directory <code>RewriteRule</code>s, 437 <code>mod_rewrite</code> aborts the request after reaching a 438 maximum number of such redirects and responds with an 500 Internal 439 Server Error. If you really need more internal redirects than 10 440 per request, you may increase the default to the desired value.</dd> 441 </dl> 442 <hr noshade="noshade" size="1" /> 443 444 <h3><a id="RewriteLog" name="RewriteLog">RewriteLog</a></h3> 445 <a href="directive-dict.html#Syntax" 446 rel="Help"><strong>Syntax:</strong></a> RewriteLog 447 <em>file-path</em><br /> 448 <a href="directive-dict.html#Default" 449 rel="Help"><strong>Default:</strong></a> <em>None</em><br /> 450 <a href="directive-dict.html#Context" 451 rel="Help"><strong>Context:</strong></a> server config, 452 virtual host<br /> 453 <a href="directive-dict.html#Override" 454 rel="Help"><strong>Override:</strong></a> <em>Not 455 applicable</em><br /> 456 <a href="directive-dict.html#Status" 457 rel="Help"><strong>Status:</strong></a> Extension<br /> 458 <a href="directive-dict.html#Module" 459 rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> 460 <a href="directive-dict.html#Compatibility" 461 rel="Help"><strong>Compatibility:</strong></a> Apache 462 1.2<br /> 463 464 465 <p>The <code>RewriteLog</code> directive sets the name of the 466 file to which the server logs any rewriting actions it 467 performs. If the name does not begin with a slash 468 ('<code>/</code>') then it is assumed to be relative to the 469 <em>Server Root</em>. The directive should occur only once 470 per server config.</p> 471 472 <table width="70%" border="0" bgcolor="#E0E0F0" 473 cellspacing="0" cellpadding="10"> 474 <tr> 475 <td><strong>Note</strong>: To disable the logging of 476 rewriting actions it is not recommended to set 477 <em>file-path</em> to <code>/dev/null</code>, because 478 although the rewriting engine does not then output to a 479 logfile it still creates the logfile output internally. 480 <strong>This will slow down the server with no advantage 481 to the administrator!</strong> To disable logging either 482 remove or comment out the <code>RewriteLog</code> 483 directive or use <code>RewriteLogLevel 0</code>!</td> 484 </tr> 485 </table> 486 487 <table width="70%" border="0" bgcolor="#E0E0F0" 488 cellspacing="0" cellpadding="10"> 489 <tr> 490 <td><strong>Security</strong>: See the <a 491 href="../misc/security_tips.html">Apache Security 492 Tips</a> document for details on why your security could 493 be compromised if the directory where logfiles are stored 494 is writable by anyone other than the user that starts the 495 server.</td> 496 </tr> 497 </table> 498 499 <p><strong>Example:</strong></p> 500 501 <blockquote> 502<pre> 503RewriteLog "/usr/local/var/apache/logs/rewrite.log" 504</pre> 505 </blockquote> 506 <hr noshade="noshade" size="1" /> 507 508 <h3><a id="RewriteLogLevel" 509 name="RewriteLogLevel">RewriteLogLevel</a></h3> 510 <a href="directive-dict.html#Syntax" 511 rel="Help"><strong>Syntax:</strong></a> RewriteLogLevel 512 <em>Level</em><br /> 513 <a href="directive-dict.html#Default" 514 rel="Help"><strong>Default:</strong></a> 515 <code>RewriteLogLevel 0</code><br /> 516 <a href="directive-dict.html#Context" 517 rel="Help"><strong>Context:</strong></a> server config, 518 virtual host<br /> 519 <a href="directive-dict.html#Override" 520 rel="Help"><strong>Override:</strong></a> <em>Not 521 applicable</em><br /> 522 <a href="directive-dict.html#Status" 523 rel="Help"><strong>Status:</strong></a> Extension<br /> 524 <a href="directive-dict.html#Module" 525 rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> 526 <a href="directive-dict.html#Compatibility" 527 rel="Help"><strong>Compatibility:</strong></a> Apache 528 1.2<br /> 529 530 531 <p>The <code>RewriteLogLevel</code> directive sets the 532 verbosity level of the rewriting logfile. The default level 0 533 means no logging, while 9 or more means that practically all 534 actions are logged.</p> 535 536 <p>To disable the logging of rewriting actions simply set 537 <em>Level</em> to 0. This disables all rewrite action 538 logs.</p> 539 540 <table width="70%" border="0" bgcolor="#E0E0F0" 541 cellspacing="0" cellpadding="10"> 542 <tr> 543 <td><strong>Notice:</strong> Using a high value for 544 <em>Level</em> will slow down your Apache server 545 dramatically! Use the rewriting logfile at a 546 <em>Level</em> greater than 2 only for debugging!</td> 547 </tr> 548 </table> 549 550 <p><strong>Example:</strong></p> 551 552 <blockquote> 553<pre> 554RewriteLogLevel 3 555</pre> 556 </blockquote> 557 <hr noshade="noshade" size="1" /> 558 559 <h3><a id="RewriteLock" 560 name="RewriteLock">RewriteLock</a></h3> 561 <a href="directive-dict.html#Syntax" 562 rel="Help"><strong>Syntax:</strong></a> RewriteLock 563 <em>file-path</em><br /> 564 <a href="directive-dict.html#Default" 565 rel="Help"><strong>Default:</strong></a> <em>None</em><br /> 566 <a href="directive-dict.html#Context" 567 rel="Help"><strong>Context:</strong></a> server config<br /> 568 <a href="directive-dict.html#Override" 569 rel="Help"><strong>Override:</strong></a> <em>Not 570 applicable</em><br /> 571 <a href="directive-dict.html#Status" 572 rel="Help"><strong>Status:</strong></a> Extension<br /> 573 <a href="directive-dict.html#Module" 574 rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> 575 <a href="directive-dict.html#Compatibility" 576 rel="Help"><strong>Compatibility:</strong></a> Apache 577 1.3<br /> 578 579 580 <p>This directive sets the filename for a synchronization 581 lockfile which mod_rewrite needs to communicate with 582 <samp>RewriteMap</samp> <em>programs</em>. Set this lockfile 583 to a local path (not on a NFS-mounted device) when you want 584 to use a rewriting map-program. It is not required for other 585 types of rewriting maps.</p> 586 <hr noshade="noshade" size="1" /> 587 588 <h3><a id="RewriteMap" name="RewriteMap">RewriteMap</a></h3> 589 <a href="directive-dict.html#Syntax" 590 rel="Help"><strong>Syntax:</strong></a> RewriteMap 591 <em>MapName</em> <em>MapType</em>:<em>MapSource</em><br /> 592 <a href="directive-dict.html#Default" 593 rel="Help"><strong>Default:</strong></a> not used per 594 default<br /> 595 <a href="directive-dict.html#Context" 596 rel="Help"><strong>Context:</strong></a> server config, 597 virtual host<br /> 598 <a href="directive-dict.html#Override" 599 rel="Help"><strong>Override:</strong></a> <em>Not 600 applicable</em><br /> 601 <a href="directive-dict.html#Status" 602 rel="Help"><strong>Status:</strong></a> Extension<br /> 603 <a href="directive-dict.html#Module" 604 rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> 605 <a href="directive-dict.html#Compatibility" 606 rel="Help"><strong>Compatibility:</strong></a> Apache 1.2 607 (partially), Apache 1.3<br /> 608 609 610 <p>The <code>RewriteMap</code> directive defines a 611 <em>Rewriting Map</em> which can be used inside rule 612 substitution strings by the mapping-functions to 613 insert/substitute fields through a key lookup. The source of 614 this lookup can be of various types.</p> 615 616 <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is 617 the name of the map and will be used to specify a 618 mapping-function for the substitution strings of a rewriting 619 rule via one of the following constructs:</p> 620 621 <blockquote> 622 <strong><code>${</code> <em>MapName</em> <code>:</code> 623 <em>LookupKey</em> <code>}</code><br /> 624 <code>${</code> <em>MapName</em> <code>:</code> 625 <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> 626 <code>}</code></strong> 627 </blockquote> 628 When such a construct occurs the map <em>MapName</em> is 629 consulted and the key <em>LookupKey</em> is looked-up. If the 630 key is found, the map-function construct is substituted by 631 <em>SubstValue</em>. If the key is not found then it is 632 substituted by <em>DefaultValue</em> or by the empty string 633 if no <em>DefaultValue</em> was specified. 634 635 <p>The following combinations for <em>MapType</em> and 636 <em>MapSource</em> can be used:</p> 637 638 <ul> 639 <li> 640 <strong>Standard Plain Text</strong><br /> 641 MapType: <code>txt</code>, MapSource: Unix filesystem 642 path to valid regular file 643 644 <p>This is the standard rewriting map feature where the 645 <em>MapSource</em> is a plain ASCII file containing 646 either blank lines, comment lines (starting with a '#' 647 character) or pairs like the following - one per 648 line.</p> 649 650 <blockquote> 651 <strong><em>MatchingKey</em> 652 <em>SubstValue</em></strong> 653 </blockquote> 654 655 <p>Example:</p> 656 657 <table border="0" cellspacing="1" cellpadding="5" 658 bgcolor="#F0F0F0"> 659 <tr> 660 <td> 661<pre> 662## 663## map.txt -- rewriting map 664## 665 666Ralf.S.Engelschall rse # Bastard Operator From Hell 667Mr.Joe.Average joe # Mr. Average 668</pre> 669 </td> 670 </tr> 671 </table> 672 673 <table border="0" cellspacing="1" cellpadding="5" 674 bgcolor="#F0F0F0"> 675 <tr> 676 <td> 677<pre> 678RewriteMap real-to-user txt:/path/to/file/map.txt 679</pre> 680 </td> 681 </tr> 682 </table> 683 </li> 684 685 <li> 686 <strong>Randomized Plain Text</strong><br /> 687 MapType: <code>rnd</code>, MapSource: Unix filesystem 688 path to valid regular file 689 690 <p>This is identical to the Standard Plain Text variant 691 above but with a special post-processing feature: After 692 looking up a value it is parsed according to contained 693 ``<code>|</code>'' characters which have the meaning of 694 ``or''. In other words they indicate a set of 695 alternatives from which the actual returned value is 696 chosen randomly. Although this sounds crazy and useless, 697 it was actually designed for load balancing in a reverse 698 proxy situation where the looked up values are server 699 names. Example:</p> 700 701 <table border="0" cellspacing="1" cellpadding="5" 702 bgcolor="#F0F0F0"> 703 <tr> 704 <td> 705<pre> 706## 707## map.txt -- rewriting map 708## 709 710static www1|www2|www3|www4 711dynamic www5|www6 712</pre> 713 </td> 714 </tr> 715 </table> 716 717 <table border="0" cellspacing="1" cellpadding="5" 718 bgcolor="#F0F0F0"> 719 <tr> 720 <td> 721<pre> 722RewriteMap servers rnd:/path/to/file/map.txt 723</pre> 724 </td> 725 </tr> 726 </table> 727 </li> 728 729 <li> 730 <strong>Hash File</strong><br /> 731 MapType: <code>dbm</code>, MapSource: Unix filesystem 732 path to valid regular file 733 734 <p>Here the source is a binary NDBM format file 735 containing the same contents as a <em>Plain Text</em> 736 format file, but in a special representation which is 737 optimized for really fast lookups. You can create such a 738 file with any NDBM tool or with the following Perl 739 script:</p> 740 741 <table border="0" cellspacing="1" cellpadding="5" 742 bgcolor="#F0F0F0"> 743 <tr> 744 <td> 745<pre> 746#!/path/to/bin/perl 747## 748## txt2dbm -- convert txt map to dbm format 749## 750 751use NDBM_File; 752use Fcntl; 753 754($txtmap, $dbmmap) = @ARGV; 755 756open(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n"; 757tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644) or die "Couldn't create $dbmmap!\n"; 758 759while (<TXT>) { 760 next if (/^\s*#/ or /^\s*$/); 761 $DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/); 762} 763 764untie %DB; 765close(TXT); 766</pre> 767 </td> 768 </tr> 769 </table> 770 771 <table border="0" cellspacing="1" cellpadding="5" 772 bgcolor="#F0F0F0"> 773 <tr> 774 <td> 775<pre> 776$ txt2dbm map.txt map.db 777</pre> 778 </td> 779 </tr> 780 </table> 781 </li> 782 783 <li> 784 <strong>Internal Function</strong><br /> 785 MapType: <code>int</code>, MapSource: Internal Apache 786 function 787 788 <p>Here the source is an internal Apache function. 789 Currently you cannot create your own, but the following 790 functions already exists:</p> 791 792 <ul> 793 <li><strong>toupper</strong>:<br /> 794 Converts the looked up key to all upper case.</li> 795 796 <li><strong>tolower</strong>:<br /> 797 Converts the looked up key to all lower case.</li> 798 799 <li><strong>escape</strong>:<br /> 800 Translates special characters in the looked up key to 801 hex-encodings.</li> 802 803 <li><strong>unescape</strong>:<br /> 804 Translates hex-encodings in the looked up key back to 805 special characters.</li> 806 </ul> 807 </li> 808 809 <li> 810 <strong>External Rewriting Program</strong><br /> 811 MapType: <code>prg</code>, MapSource: Unix filesystem 812 path to valid regular file 813 814 <p>Here the source is a program, not a map file. To 815 create it you can use the language of your choice, but 816 the result has to be a executable (<em>i.e.</em>, either 817 object-code or a script with the magic cookie trick 818 '<code>#!/path/to/interpreter</code>' as the first 819 line).</p> 820 821 <p>This program is started once at startup of the Apache 822 servers and then communicates with the rewriting engine 823 over its <code>stdin</code> and <code>stdout</code> 824 file-handles. For each map-function lookup it will 825 receive the key to lookup as a newline-terminated string 826 on <code>stdin</code>. It then has to give back the 827 looked-up value as a newline-terminated string on 828 <code>stdout</code> or the four-character string 829 ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there 830 is no corresponding value for the given key). A trivial 831 program which will implement a 1:1 map (<em>i.e.</em>, 832 key == value) could be:</p> 833 834 <table border="0" cellspacing="1" cellpadding="5" 835 bgcolor="#F0F0F0"> 836 <tr> 837 <td> 838<pre> 839#!/usr/bin/perl 840$| = 1; 841while (<STDIN>) { 842 # ...put here any transformations or lookups... 843 print $_; 844} 845</pre> 846 </td> 847 </tr> 848 </table> 849 850 <p>But be very careful:<br /> 851 </p> 852 853 <ol> 854 <li>``<em>Keep it simple, stupid</em>'' (KISS), because 855 if this program hangs it will hang the Apache server 856 when the rule occurs.</li> 857 858 <li>Avoid one common mistake: never do buffered I/O on 859 <code>stdout</code>! This will cause a deadloop! Hence 860 the ``<code>$|=1</code>'' in the above example...</li> 861 862 <li>Use the <samp>RewriteLock</samp> directive to 863 define a lockfile mod_rewrite can use to synchronize 864 the communication to the program. By default no such 865 synchronization takes place.</li> 866 </ol> 867 </li> 868 </ul> 869 The <code>RewriteMap</code> directive can occur more than 870 once. For each mapping-function use one 871 <code>RewriteMap</code> directive to declare its rewriting 872 mapfile. While you cannot <strong>declare</strong> a map in 873 per-directory context it is of course possible to 874 <strong>use</strong> this map in per-directory context. 875 876 <table width="70%" border="0" bgcolor="#E0E0F0" 877 cellspacing="0" cellpadding="10"> 878 <tr> 879 <td><strong>Note:</strong> For plain text and DBM format 880 files the looked-up keys are cached in-core until the 881 <code>mtime</code> of the mapfile changes or the server 882 does a restart. This way you can have map-functions in 883 rules which are used for <strong>every</strong> request. 884 This is no problem, because the external lookup only 885 happens once!</td> 886 </tr> 887 </table> 888 <hr noshade="noshade" size="1" /> 889 890 <h3><a id="RewriteBase" 891 name="RewriteBase">RewriteBase</a></h3> 892 <a href="directive-dict.html#Syntax" 893 rel="Help"><strong>Syntax:</strong></a> RewriteBase 894 <em>URL-path</em><br /> 895 <a href="directive-dict.html#Default" 896 rel="Help"><strong>Default:</strong></a> <em>default is the 897 physical directory path</em><br /> 898 <a href="directive-dict.html#Context" 899 rel="Help"><strong>Context:</strong></a> directory, 900 .htaccess<br /> 901 <a href="directive-dict.html#Override" 902 rel="Help"><strong>Override:</strong></a> 903 <em>FileInfo</em><br /> 904 <a href="directive-dict.html#Status" 905 rel="Help"><strong>Status:</strong></a> Extension<br /> 906 <a href="directive-dict.html#Module" 907 rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> 908 <a href="directive-dict.html#Compatibility" 909 rel="Help"><strong>Compatibility:</strong></a> Apache 910 1.2<br /> 911 912 913 <p>The <code>RewriteBase</code> directive explicitly sets the 914 base URL for per-directory rewrites. As you will see below, 915 <code>RewriteRule</code> can be used in per-directory config 916 files (<code>.htaccess</code>). There it will act locally, 917 <em>i.e.</em>, the local directory prefix is stripped at this 918 stage of processing and your rewriting rules act only on the 919 remainder. At the end it is automatically added back to the 920 path.</p> 921 922 <p>When a substitution occurs for a new URL, this module has 923 to re-inject the URL into the server processing. To be able 924 to do this it needs to know what the corresponding URL-prefix 925 or URL-base is. By default this prefix is the corresponding 926 filepath itself. <strong>But at most websites URLs are NOT 927 directly related to physical filename paths, so this 928 assumption will usually be wrong!</strong> There you have to 929 use the <code>RewriteBase</code> directive to specify the 930 correct URL-prefix.</p> 931 932 <table width="70%" border="0" bgcolor="#E0E0F0" 933 cellspacing="0" cellpadding="10"> 934 <tr> 935 <td><strong>Notice:</strong> If your webserver's URLs are 936 <strong>not</strong> directly related to physical file 937 paths, you have to use <code>RewriteBase</code> in every 938 <code>.htaccess</code> files where you want to use 939 <code>RewriteRule</code> directives.</td> 940 </tr> 941 </table> 942 943 <p><strong>Example:</strong></p> 944 945 <blockquote> 946 Assume the following per-directory config file: 947 948 <table border="0" cellspacing="1" cellpadding="5" 949 bgcolor="#F0F0F0"> 950 <tr> 951 <td> 952<pre> 953# 954# /abc/def/.htaccess -- per-dir config file for directory /abc/def 955# Remember: /abc/def is the physical path of /xyz, <em>i.e.</em>, the server 956# has a 'Alias /xyz /abc/def' directive <em>e.g.</em> 957# 958 959RewriteEngine On 960 961# let the server know that we were reached via /xyz and not 962# via the physical path prefix /abc/def 963RewriteBase /xyz 964 965# now the rewriting rules 966RewriteRule ^oldstuff\.html$ newstuff.html 967</pre> 968 </td> 969 </tr> 970 </table> 971 972 <p>In the above example, a request to 973 <code>/xyz/oldstuff.html</code> gets correctly rewritten to 974 the physical file <code>/abc/def/newstuff.html</code>.</p> 975 976 <table width="70%" border="0" bgcolor="#E0E0F0" 977 cellspacing="0" cellpadding="10"> 978 <tr> 979 <td> 980 <font size="-1"><strong>Note - For Apache 981 hackers:</strong><br /> 982 The following list gives detailed information about 983 the internal processing steps:</font> 984<pre> 985<font size="-1">Request: 986 /xyz/oldstuff.html 987 988Internal Processing: 989 /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias) 990 /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule) 991 /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase) 992 /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias) 993 994Result: 995 /abc/def/newstuff.html 996</font> 997</pre> 998 <font size="-1">This seems very complicated but is 999 the correct Apache internal processing, because the 1000 per-directory rewriting comes too late in the 1001 process. So, when it occurs the (rewritten) request 1002 has to be re-injected into the Apache kernel! BUT: 1003 While this seems like a serious overhead, it really 1004 isn't, because this re-injection happens fully 1005 internally to the Apache server and the same 1006 procedure is used by many other operations inside 1007 Apache. So, you can be sure the design and 1008 implementation is correct.</font> 1009 </td> 1010 </tr> 1011 </table> 1012 </blockquote> 1013 <hr noshade="noshade" size="1" /> 1014 1015 <h3><a id="RewriteCond" 1016 name="RewriteCond">RewriteCond</a></h3> 1017 <a href="directive-dict.html#Syntax" 1018 rel="Help"><strong>Syntax:</strong></a> RewriteCond 1019 <em>TestString</em> <em>CondPattern</em><br /> 1020 <a href="directive-dict.html#Default" 1021 rel="Help"><strong>Default:</strong></a> <em>None</em><br /> 1022 <a href="directive-dict.html#Context" 1023 rel="Help"><strong>Context:</strong></a> server config, 1024 virtual host, directory, .htaccess<br /> 1025 <a href="directive-dict.html#Override" 1026 rel="Help"><strong>Override:</strong></a> 1027 <em>FileInfo</em><br /> 1028 <a href="directive-dict.html#Status" 1029 rel="Help"><strong>Status:</strong></a> Extension<br /> 1030 <a href="directive-dict.html#Module" 1031 rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> 1032 <a href="directive-dict.html#Compatibility" 1033 rel="Help"><strong>Compatibility:</strong></a> Apache 1.2 1034 (partially), Apache 1.3<br /> 1035 1036 1037 <p>The <code>RewriteCond</code> directive defines a rule 1038 condition. Precede a <code>RewriteRule</code> directive with 1039 one or more <code>RewriteCond</code> directives. The 1040 following rewriting rule is only used if its pattern matches 1041 the current state of the URI <strong>and</strong> if these 1042 additional conditions apply too.</p> 1043 1044 <p><em>TestString</em> is a string which can contains the 1045 following expanded constructs in addition to plain text:</p> 1046 1047 <ul> 1048 <li> 1049 <strong>RewriteRule backreferences</strong>: These are 1050 backreferences of the form 1051 1052 <blockquote> 1053 <strong><code>$N</code></strong> 1054 </blockquote> 1055 (0 <= N <= 9) which provide access to the grouped 1056 parts (parenthesis!) of the pattern from the 1057 corresponding <code>RewriteRule</code> directive (the one 1058 following the current bunch of <code>RewriteCond</code> 1059 directives). 1060 </li> 1061 1062 <li> 1063 <strong>RewriteCond backreferences</strong>: These are 1064 backreferences of the form 1065 1066 <blockquote> 1067 <strong><code>%N</code></strong> 1068 </blockquote> 1069 (1 <= N <= 9) which provide access to the grouped 1070 parts (parentheses!) of the pattern from the last matched 1071 <code>RewriteCond</code> directive in the current bunch 1072 of conditions. 1073 </li> 1074 1075 <li> 1076 <strong>RewriteMap expansions</strong>: These are 1077 expansions of the form 1078 1079 <blockquote> 1080 <strong><code>${mapname:key|default}</code></strong> 1081 </blockquote> 1082 See <a href="#mapfunc">the documentation for 1083 RewriteMap</a> for more details. 1084 </li> 1085 1086 <li> 1087 <strong>Server-Variables</strong>: These are variables of 1088 the form 1089 1090 <blockquote> 1091 <strong><code>%{</code> <em>NAME_OF_VARIABLE</em> 1092 <code>}</code></strong> 1093 </blockquote> 1094 where <em>NAME_OF_VARIABLE</em> can be a string taken 1095 from the following list: 1096 1097 <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5"> 1098 <tr> 1099 <td valign="TOP"> 1100 <strong>HTTP headers:</strong> 1101 1102 <p><font size="-1">HTTP_USER_AGENT<br /> 1103 HTTP_REFERER<br /> 1104 HTTP_COOKIE<br /> 1105 HTTP_FORWARDED<br /> 1106 HTTP_HOST<br /> 1107 HTTP_PROXY_CONNECTION<br /> 1108 HTTP_ACCEPT<br /> 1109 </font></p> 1110 </td> 1111 1112 <td valign="TOP"> 1113 <strong>connection & request:</strong> 1114 1115 <p><font size="-1">REMOTE_ADDR<br /> 1116 REMOTE_HOST<br /> 1117 REMOTE_USER<br /> 1118 REMOTE_IDENT<br /> 1119 REQUEST_METHOD<br /> 1120 SCRIPT_FILENAME<br /> 1121 PATH_INFO<br /> 1122 QUERY_STRING<br /> 1123 AUTH_TYPE<br /> 1124 </font></p> 1125 </td> 1126 </tr> 1127 1128 <tr> 1129 <td valign="TOP"> 1130 <strong>server internals:</strong> 1131 1132 <p><font size="-1">DOCUMENT_ROOT<br /> 1133 SERVER_ADMIN<br /> 1134 SERVER_NAME<br /> 1135 SERVER_ADDR<br /> 1136 SERVER_PORT<br /> 1137 SERVER_PROTOCOL<br /> 1138 SERVER_SOFTWARE<br /> 1139 </font></p> 1140 </td> 1141 1142 <td valign="TOP"> 1143 <strong>system stuff:</strong> 1144 1145 <p><font size="-1">TIME_YEAR<br /> 1146 TIME_MON<br /> 1147 TIME_DAY<br /> 1148 TIME_HOUR<br /> 1149 TIME_MIN<br /> 1150 TIME_SEC<br /> 1151 TIME_WDAY<br /> 1152 TIME<br /> 1153 </font></p> 1154 </td> 1155 1156 <td valign="TOP"> 1157 <strong>specials:</strong> 1158 1159 <p><font size="-1">API_VERSION<br /> 1160 THE_REQUEST<br /> 1161 REQUEST_URI<br /> 1162 REQUEST_FILENAME<br /> 1163 IS_SUBREQ<br /> 1164 </font></p> 1165 </td> 1166 </tr> 1167 </table> 1168 1169 <table width="70%" border="0" bgcolor="#E0E0F0" 1170 cellspacing="0" cellpadding="10"> 1171 <tr> 1172 <td> 1173 <p><strong>Notice:</strong> These variables all 1174 correspond to the similarly named HTTP 1175 MIME-headers, C variables of the Apache server or 1176 <code>struct tm</code> fields of the Unix system. 1177 Most are documented elsewhere in the Manual or in 1178 the CGI specification. Those that are special to 1179 mod_rewrite include:</p> 1180 1181 <dl> 1182 <dt><code>IS_SUBREQ</code></dt> 1183 1184 <dd>Will contain the text "true" if the request 1185 currently being processed is a sub-request, 1186 "false" otherwise. Sub-requests may be generated 1187 by modules that need to resolve additional files 1188 or URIs in order to complete their tasks.</dd> 1189 1190 <dt><code>API_VERSION</code></dt> 1191 1192 <dd>This is the version of the Apache module API 1193 (the internal interface between server and 1194 module) in the current httpd build, as defined in 1195 include/ap_mmn.h. The module API version 1196 corresponds to the version of Apache in use (in 1197 the release version of Apache 1.3.14, for 1198 instance, it is 19990320:10), but is mainly of 1199 interest to module authors.</dd> 1200 1201 <dt><code>THE_REQUEST</code></dt> 1202 1203 <dd>The full HTTP request line sent by the 1204 browser to the server (e.g., "<code>GET 1205 /index.html HTTP/1.1</code>"). This does not 1206 include any additional headers sent by the 1207 browser.</dd> 1208 1209 <dt><code>REQUEST_URI</code></dt> 1210 1211 <dd>The resource requested in the HTTP request 1212 line. (In the example above, this would be 1213 "/index.html".)</dd> 1214 1215 <dt><code>REQUEST_FILENAME</code></dt> 1216 1217 <dd>The full local filesystem path to the file or 1218 script matching the request.</dd> 1219 </dl> 1220 </td> 1221 </tr> 1222 </table> 1223 </li> 1224 </ul> 1225 1226 <p>Special Notes:</p> 1227 1228 <ol> 1229 <li>The variables SCRIPT_FILENAME and REQUEST_FILENAME 1230 contain the same value, <em>i.e.</em>, the value of the 1231 <code>filename</code> field of the internal 1232 <code>request_rec</code> structure of the Apache server. 1233 The first name is just the commonly known CGI variable name 1234 while the second is the consistent counterpart to 1235 REQUEST_URI (which contains the value of the 1236 <code>uri</code> field of <code>request_rec</code>).</li> 1237 1238 <li>There is the special format: 1239 <code>%{ENV:variable}</code> where <em>variable</em> can be 1240 any environment variable. This is looked-up via internal 1241 Apache structures and (if not found there) via 1242 <code>getenv()</code> from the Apache server process.</li> 1243 1244 <li>There is the special format: 1245 <code>%{HTTP:header}</code> where <em>header</em> can be 1246 any HTTP MIME-header name. This is looked-up from the HTTP 1247 request. Example: <code>%{HTTP:Proxy-Connection}</code> is 1248 the value of the HTTP header 1249 ``<code>Proxy-Connection:</code>''.</li> 1250 1251 <li>There is the special format 1252 <code>%{LA-U:variable}</code> for look-aheads which perform 1253 an internal (URL-based) sub-request to determine the final 1254 value of <em>variable</em>. Use this when you want to use a 1255 variable for rewriting which is actually set later in an 1256 API phase and thus is not available at the current stage. 1257 For instance when you want to rewrite according to the 1258 <code>REMOTE_USER</code> variable from within the 1259 per-server context (<code>httpd.conf</code> file) you have 1260 to use <code>%{LA-U:REMOTE_USER}</code> because this 1261 variable is set by the authorization phases which come 1262 <em>after</em> the URL translation phase where mod_rewrite 1263 operates. On the other hand, because mod_rewrite implements 1264 its per-directory context (<code>.htaccess</code> file) via 1265 the Fixup phase of the API and because the authorization 1266 phases come <em>before</em> this phase, you just can use 1267 <code>%{REMOTE_USER}</code> there.</li> 1268 1269 <li>There is the special format: 1270 <code>%{LA-F:variable}</code> which performs an internal 1271 (filename-based) sub-request to determine the final value 1272 of <em>variable</em>. Most of the time this is the same as 1273 LA-U above.</li> 1274 </ol> 1275 1276 <p><em>CondPattern</em> is the condition pattern, 1277 <em>i.e.</em>, a regular expression which is applied to the 1278 current instance of the <em>TestString</em>, <em>i.e.</em>, 1279 <em>TestString</em> is evaluated and then matched against 1280 <em>CondPattern</em>.</p> 1281 1282 <p><strong>Remember:</strong> <em>CondPattern</em> is a 1283 standard <em>Extended Regular Expression</em> with some 1284 additions:</p> 1285 1286 <ol> 1287 <li>You can prefix the pattern string with a 1288 '<code>!</code>' character (exclamation mark) to specify a 1289 <strong>non</strong>-matching pattern.</li> 1290 1291 <li> 1292 There are some special variants of <em>CondPatterns</em>. 1293 Instead of real regular expression strings you can also 1294 use one of the following: 1295 1296 <ul> 1297 <li>'<strong><CondPattern</strong>' (is lexically 1298 lower)<br /> 1299 Treats the <em>CondPattern</em> as a plain string and 1300 compares it lexically to <em>TestString</em>. True if 1301 <em>TestString</em> is lexically lower than 1302 <em>CondPattern</em>.</li> 1303 1304 <li>'<strong>>CondPattern</strong>' (is lexically 1305 greater)<br /> 1306 Treats the <em>CondPattern</em> as a plain string and 1307 compares it lexically to <em>TestString</em>. True if 1308 <em>TestString</em> is lexically greater than 1309 <em>CondPattern</em>.</li> 1310 1311 <li>'<strong>=CondPattern</strong>' (is lexically 1312 equal)<br /> 1313 Treats the <em>CondPattern</em> as a plain string and 1314 compares it lexically to <em>TestString</em>. True if 1315 <em>TestString</em> is lexically equal to 1316 <em>CondPattern</em>, i.e the two strings are exactly 1317 equal (character by character). If <em>CondPattern</em> 1318 is just <samp>""</samp> (two quotation marks) this 1319 compares <em>TestString</em> to the empty string.</li> 1320 1321 <li>'<strong>-d</strong>' (is 1322 <strong>d</strong>irectory)<br /> 1323 Treats the <em>TestString</em> as a pathname and tests 1324 if it exists and is a directory.</li> 1325 1326 <li>'<strong>-f</strong>' (is regular 1327 <strong>f</strong>ile)<br /> 1328 Treats the <em>TestString</em> as a pathname and tests 1329 if it exists and is a regular file.</li> 1330 1331 <li>'<strong>-s</strong>' (is regular file with 1332 <strong>s</strong>ize)<br /> 1333 Treats the <em>TestString</em> as a pathname and tests 1334 if it exists and is a regular file with size greater 1335 than zero.</li> 1336 1337 <li>'<strong>-l</strong>' (is symbolic 1338 <strong>l</strong>ink)<br /> 1339 Treats the <em>TestString</em> as a pathname and tests 1340 if it exists and is a symbolic link.</li> 1341 1342 <li>'<strong>-F</strong>' (is existing file via 1343 subrequest)<br /> 1344 Checks if <em>TestString</em> is a valid file and 1345 accessible via all the server's currently-configured 1346 access controls for that path. This uses an internal 1347 subrequest to determine the check, so use it with care 1348 because it decreases your servers performance!</li> 1349 1350 <li>'<strong>-U</strong>' (is existing URL via 1351 subrequest)<br /> 1352 Checks if <em>TestString</em> is a valid URL and 1353 accessible via all the server's currently-configured 1354 access controls for that path. This uses an internal 1355 subrequest to determine the check, so use it with care 1356 because it decreases your server's performance!</li> 1357 </ul> 1358 1359 <table width="70%" border="0" bgcolor="#E0E0F0" 1360 cellspacing="0" cellpadding="10"> 1361 <tr> 1362 <td><strong>Notice:</strong> All of these tests can 1363 also be prefixed by an exclamation mark ('!') to 1364 negate their meaning.</td> 1365 </tr> 1366 </table> 1367 </li> 1368 </ol> 1369 1370 <p>Additionally you can set special flags for 1371 <em>CondPattern</em> by appending</p> 1372 1373 <blockquote> 1374 <strong><code>[</code><em>flags</em><code>]</code></strong> 1375 </blockquote> 1376 as the third argument to the <code>RewriteCond</code> 1377 directive. <em>Flags</em> is a comma-separated list of the 1378 following flags: 1379 1380 <ul> 1381 <li>'<strong><code>nocase|NC</code></strong>' 1382 (<strong>n</strong>o <strong>c</strong>ase)<br /> 1383 This makes the test case-insensitive, <em>i.e.</em>, there 1384 is no difference between 'A-Z' and 'a-z' both in the 1385 expanded <em>TestString</em> and the <em>CondPattern</em>. 1386 This flag is effective only for comparisons between 1387 <em>TestString</em> and <em>CondPattern</em>. It has no 1388 effect on filesystem and subrequest checks.</li> 1389 1390 <li> 1391 '<strong><code>ornext|OR</code></strong>' 1392 (<strong>or</strong> next condition)<br /> 1393 Use this to combine rule conditions with a local OR 1394 instead of the implicit AND. Typical example: 1395 1396 <blockquote> 1397<pre> 1398RewriteCond %{REMOTE_HOST} ^host1.* [OR] 1399RewriteCond %{REMOTE_HOST} ^host2.* [OR] 1400RewriteCond %{REMOTE_HOST} ^host3.* 1401RewriteRule ...some special stuff for any of these hosts... 1402</pre> 1403 </blockquote> 1404 Without this flag you would have to write the cond/rule 1405 three times. 1406 </li> 1407 </ul> 1408 1409 <p><strong>Example:</strong></p> 1410 1411 <blockquote> 1412 To rewrite the Homepage of a site according to the 1413 ``<code>User-Agent:</code>'' header of the request, you can 1414 use the following: 1415 1416 <blockquote> 1417<pre> 1418RewriteCond %{HTTP_USER_AGENT} ^Mozilla.* 1419RewriteRule ^/$ /homepage.max.html [L] 1420 1421RewriteCond %{HTTP_USER_AGENT} ^Lynx.* 1422RewriteRule ^/$ /homepage.min.html [L] 1423 1424RewriteRule ^/$ /homepage.std.html [L] 1425</pre> 1426 </blockquote> 1427 Interpretation: If you use Netscape Navigator as your 1428 browser (which identifies itself as 'Mozilla'), then you 1429 get the max homepage, which includes Frames, <em>etc.</em> 1430 If you use the Lynx browser (which is Terminal-based), then 1431 you get the min homepage, which contains no images, no 1432 tables, <em>etc.</em> If you use any other browser you get 1433 the standard homepage. 1434 </blockquote> 1435 <hr noshade="noshade" size="1" /> 1436 1437 <h3><a id="RewriteRule" 1438 name="RewriteRule">RewriteRule</a></h3> 1439 <a href="directive-dict.html#Syntax" 1440 rel="Help"><strong>Syntax:</strong></a> RewriteRule 1441 <em>Pattern</em> <em>Substitution</em><br /> 1442 <a href="directive-dict.html#Default" 1443 rel="Help"><strong>Default:</strong></a> <em>None</em><br /> 1444 <a href="directive-dict.html#Context" 1445 rel="Help"><strong>Context:</strong></a> server config, 1446 virtual host, directory, .htaccess<br /> 1447 <a href="directive-dict.html#Override" 1448 rel="Help"><strong>Override:</strong></a> 1449 <em>FileInfo</em><br /> 1450 <a href="directive-dict.html#Status" 1451 rel="Help"><strong>Status:</strong></a> Extension<br /> 1452 <a href="directive-dict.html#Module" 1453 rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> 1454 <a href="directive-dict.html#Compatibility" 1455 rel="Help"><strong>Compatibility:</strong></a> Apache 1.2 1456 (partially), Apache 1.3<br /> 1457 1458 1459 <p>The <code>RewriteRule</code> directive is the real 1460 rewriting workhorse. The directive can occur more than once. 1461 Each directive then defines one single rewriting rule. The 1462 <strong>definition order</strong> of these rules is 1463 <strong>important</strong>, because this order is used when 1464 applying the rules at run-time.</p> 1465 1466 <p><a id="patterns" name="patterns"><em>Pattern</em></a> can 1467 be (for Apache 1.1.x a System V8 and for Apache 1.2.x and 1468 later a POSIX) <a id="regexp" name="regexp">regular 1469 expression</a> which gets applied to the current URL. Here 1470 ``current'' means the value of the URL when this rule gets 1471 applied. This may not be the originally requested URL, 1472 because any number of rules may already 1473 have matched and made alterations to it.</p> 1474 1475 <p>Some hints about the syntax of regular expressions:</p> 1476 1477 <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5"> 1478 <tr> 1479 <td valign="TOP"> 1480<pre> 1481<strong>Text:</strong> 1482 <strong><code>.</code></strong> Any single character 1483 <strong><code>[</code></strong>chars<strong><code>]</code></strong> Character class: One of chars 1484 <strong><code>[^</code></strong>chars<strong><code>]</code></strong> Character class: None of chars 1485 text1<strong><code>|</code></strong>text2 Alternative: text1 or text2 1486 1487<strong>Quantifiers:</strong> 1488 <strong><code>?</code></strong> 0 or 1 of the preceding text 1489 <strong><code>*</code></strong> 0 or N of the preceding text (N > 0) 1490 <strong><code>+</code></strong> 1 or N of the preceding text (N > 1) 1491 1492<strong>Grouping:</strong> 1493 <strong><code>(</code></strong>text<strong><code>)</code></strong> Grouping of text 1494 (either to set the borders of an alternative or 1495 for making backreferences where the <strong>N</strong>th group can 1496 be used on the RHS of a RewriteRule with <code>$</code><strong>N</strong>) 1497 1498<strong>Anchors:</strong> 1499 <strong><code>^</code></strong> Start of line anchor 1500 <strong><code>$</code></strong> End of line anchor 1501 1502<strong>Escaping:</strong> 1503 <strong><code>\</code></strong>char escape that particular char 1504 (for instance to specify the chars "<code>.[]()</code>" <em>etc.</em>) 1505</pre> 1506 </td> 1507 </tr> 1508 </table> 1509 1510 <p>For more information about regular expressions either have 1511 a look at your local regex(3) manpage or its 1512 <code>src/regex/regex.3</code> copy in the Apache 1.3 1513 distribution. If you are interested in more detailed 1514 information about regular expressions and their variants 1515 (POSIX regex, Perl regex, <em>etc.</em>) have a look at the 1516 following dedicated book on this topic:</p> 1517 1518 <blockquote> 1519 <em>Mastering Regular Expressions</em><br /> 1520 Jeffrey E.F. Friedl<br /> 1521 Nutshell Handbook Series<br /> 1522 O'Reilly & Associates, Inc. 1997<br /> 1523 ISBN 1-56592-257-3<br /> 1524 </blockquote> 1525 1526 <p>Additionally in mod_rewrite the NOT character 1527 ('<code>!</code>') is a possible pattern prefix. This gives 1528 you the ability to negate a pattern; to say, for instance: 1529 ``<em>if the current URL does <strong>NOT</strong> match this 1530 pattern</em>''. This can be used for exceptional cases, where 1531 it is easier to match the negative pattern, or as a last 1532 default rule.</p> 1533 1534 <table width="70%" border="0" bgcolor="#E0E0F0" 1535 cellspacing="0" cellpadding="10"> 1536 <tr> 1537 <td><strong>Notice:</strong> When using the NOT character 1538 to negate a pattern you cannot have grouped wildcard 1539 parts in the pattern. This is impossible because when the 1540 pattern does NOT match, there are no contents for the 1541 groups. In consequence, if negated patterns are used, you 1542 cannot use <code>$N</code> in the substitution 1543 string!</td> 1544 </tr> 1545 </table> 1546 1547 <p><a id="rhs" name="rhs"><em>Substitution</em></a> of a 1548 rewriting rule is the string which is substituted for (or 1549 replaces) the original URL for which <em>Pattern</em> 1550 matched. Beside plain text you can use</p> 1551 1552 <ol> 1553 <li>back-references <code>$N</code> to the RewriteRule 1554 pattern</li> 1555 1556 <li>back-references <code>%N</code> to the last matched 1557 RewriteCond pattern</li> 1558 1559 <li>server-variables as in rule condition test-strings 1560 (<code>%{VARNAME}</code>)</li> 1561 1562 <li><a href="#mapfunc">mapping-function</a> calls 1563 (<code>${mapname:key|default}</code>)</li> 1564 </ol> 1565 Back-references are <code>$</code><strong>N</strong> 1566 (<strong>N</strong>=0..9) identifiers which will be replaced 1567 by the contents of the <strong>N</strong>th group of the 1568 matched <em>Pattern</em>. The server-variables are the same 1569 as for the <em>TestString</em> of a <code>RewriteCond</code> 1570 directive. The mapping-functions come from the 1571 <code>RewriteMap</code> directive and are explained there. 1572 These three types of variables are expanded in the order of 1573 the above list. 1574 1575 <p>As already mentioned above, all the rewriting rules are 1576 applied to the <em>Substitution</em> (in the order of 1577 definition in the config file). The URL is <strong>completely 1578 replaced</strong> by the <em>Substitution</em> and the 1579 rewriting process goes on until there are no more rules 1580 unless explicitly terminated by a 1581 <code><strong>L</strong></code> flag - see below.</p> 1582 1583 <p>There is a special substitution string named 1584 '<code>-</code>' which means: <strong>NO 1585 substitution</strong>! Sounds silly? No, it is useful to 1586 provide rewriting rules which <strong>only</strong> match 1587 some URLs but do no substitution, <em>e.g.</em>, in 1588 conjunction with the <strong>C</strong> (chain) flag to be 1589 able to have more than one pattern to be applied before a 1590 substitution occurs.</p> 1591 1592 <p>One more note: You can even create URLs in the 1593 substitution string containing a query string part. Just use 1594 a question mark inside the substitution string to indicate 1595 that the following stuff should be re-injected into the 1596 QUERY_STRING. When you want to erase an existing query 1597 string, end the substitution string with just the question 1598 mark.</p> 1599 1600 <table width="70%" border="0" bgcolor="#E0E0F0" 1601 cellspacing="0" cellpadding="10"> 1602 <tr> 1603 <td><strong>Note</strong>: There is a special feature: 1604 When you prefix a substitution field with 1605 <code>http://</code><em>thishost</em>[<em>:thisport</em>] 1606 then <strong>mod_rewrite</strong> automatically strips it 1607 out. This auto-reduction on implicit external redirect 1608 URLs is a useful and important feature when used in 1609 combination with a mapping-function which generates the 1610 hostname part. Have a look at the first example in the 1611 example section below to understand this.</td> 1612 </tr> 1613 </table> 1614 1615 <table width="70%" border="0" bgcolor="#E0E0F0" 1616 cellspacing="0" cellpadding="10"> 1617 <tr> 1618 <td><strong>Remember:</strong> An unconditional external 1619 redirect to your own server will not work with the prefix 1620 <code>http://thishost</code> because of this feature. To 1621 achieve such a self-redirect, you have to use the 1622 <strong>R</strong>-flag (see below).</td> 1623 </tr> 1624 </table> 1625 1626 <p>Additionally you can set special flags for 1627 <em>Substitution</em> by appending</p> 1628 1629 <blockquote> 1630 <strong><code>[</code><em>flags</em><code>]</code></strong> 1631 </blockquote> 1632 as the third argument to the <code>RewriteRule</code> 1633 directive. <em>Flags</em> is a comma-separated list of the 1634 following flags: 1635 1636 <ul> 1637 <li> 1638 '<strong><code>redirect|R</code> 1639 [=<em>code</em>]</strong>' (force <a id="redirect" 1640 name="redirect"><strong>r</strong>edirect</a>)<br /> 1641 Prefix <em>Substitution</em> with 1642 <code>http://thishost[:thisport]/</code> (which makes the 1643 new URL a URI) to force a external redirection. If no 1644 <em>code</em> is given a HTTP response of 302 (MOVED 1645 TEMPORARILY) is used. If you want to use other response 1646 codes in the range 300-400 just specify them as a number 1647 or use one of the following symbolic names: 1648 <code>temp</code> (default), <code>permanent</code>, 1649 <code>seeother</code>. Use it for rules which should 1650 canonicalize the URL and give it back to the client, 1651 <em>e.g.</em>, translate ``<code>/~</code>'' into 1652 ``<code>/u/</code>'' or always append a slash to 1653 <code>/u/</code><em>user</em>, etc.<br /> 1654 1655 1656 <p><strong>Note:</strong> When you use this flag, make 1657 sure that the substitution field is a valid URL! If not, 1658 you are redirecting to an invalid location! And remember 1659 that this flag itself only prefixes the URL with 1660 <code>http://thishost[:thisport]/</code>, rewriting 1661 continues. Usually you also want to stop and do the 1662 redirection immediately. To stop the rewriting you also 1663 have to provide the 'L' flag.</p> 1664 </li> 1665 1666 <li>'<strong><code>forbidden|F</code></strong>' (force URL 1667 to be <strong>f</strong>orbidden)<br /> 1668 This forces the current URL to be forbidden, 1669 <em>i.e.</em>, it immediately sends back a HTTP response of 1670 403 (FORBIDDEN). Use this flag in conjunction with 1671 appropriate RewriteConds to conditionally block some 1672 URLs.</li> 1673 1674 <li>'<strong><code>gone|G</code></strong>' (force URL to be 1675 <strong>g</strong>one)<br /> 1676 This forces the current URL to be gone, <em>i.e.</em>, it 1677 immediately sends back a HTTP response of 410 (GONE). Use 1678 this flag to mark pages which no longer exist as gone.</li> 1679 1680 <li> 1681 '<strong><code>proxy|P</code></strong>' (force 1682 <strong>p</strong>roxy)<br /> 1683 This flag forces the substitution part to be internally 1684 forced as a proxy request and immediately (<em>i.e.</em>, 1685 rewriting rule processing stops here) put through the <a 1686 href="mod_proxy.html">proxy module</a>. You have to make 1687 sure that the substitution string is a valid URI 1688 (<em>e.g.</em>, typically starting with 1689 <code>http://</code><em>hostname</em>) which can be 1690 handled by the Apache proxy module. If not you get an 1691 error from the proxy module. Use this flag to achieve a 1692 more powerful implementation of the <a 1693 href="mod_proxy.html#proxypass">ProxyPass</a> directive, 1694 to map some remote stuff into the namespace of the local 1695 server. 1696 1697 <p>Notice: To use this functionality make sure you have 1698 the proxy module compiled into your Apache server 1699 program. If you don't know please check whether 1700 <code>mod_proxy.c</code> is part of the ``<code>httpd 1701 -l</code>'' output. If yes, this functionality is 1702 available to mod_rewrite. If not, then you first have to 1703 rebuild the ``<code>httpd</code>'' program with mod_proxy 1704 enabled.</p> 1705 </li> 1706 1707 <li>'<strong><code>last|L</code></strong>' 1708 (<strong>l</strong>ast rule)<br /> 1709 Stop the rewriting process here and don't apply any more 1710 rewriting rules. This corresponds to the Perl 1711 <code>last</code> command or the <code>break</code> command 1712 from the C language. Use this flag to prevent the currently 1713 rewritten URL from being rewritten further by following 1714 rules. For example, use it to rewrite the root-path URL 1715 ('<code>/</code>') to a real one, <em>e.g.</em>, 1716 '<code>/e/www/</code>'.</li> 1717 1718 <li>'<strong><code>next|N</code></strong>' 1719 (<strong>n</strong>ext round)<br /> 1720 Re-run the rewriting process (starting again with the 1721 first rewriting rule). Here the URL to match is again not 1722 the original URL but the URL from the last rewriting rule. 1723 This corresponds to the Perl <code>next</code> command or 1724 the <code>continue</code> command from the C language. Use 1725 this flag to restart the rewriting process, <em>i.e.</em>, 1726 to immediately go to the top of the loop.<br /> 1727 <strong>But be careful not to create an infinite 1728 loop!</strong></li> 1729 1730 <li>'<strong><code>chain|C</code></strong>' 1731 (<strong>c</strong>hained with next rule)<br /> 1732 This flag chains the current rule with the next rule 1733 (which itself can be chained with the following rule, 1734 <em>etc.</em>). This has the following effect: if a rule 1735 matches, then processing continues as usual, <em>i.e.</em>, 1736 the flag has no effect. If the rule does 1737 <strong>not</strong> match, then all following chained 1738 rules are skipped. For instance, use it to remove the 1739 ``<code>.www</code>'' part inside a per-directory rule set 1740 when you let an external redirect happen (where the 1741 ``<code>.www</code>'' part should not to occur!).</li> 1742 1743 <li> 1744 '<strong><code>type|T</code></strong>=<em>MIME-type</em>' 1745 (force MIME <strong>t</strong>ype)<br /> 1746 Force the MIME-type of the target file to be 1747 <em>MIME-type</em>. For instance, this can be used to 1748 simulate the <code>mod_alias</code> directive 1749 <code>ScriptAlias</code> which internally forces all files 1750 inside the mapped directory to have a MIME type of 1751 ``<code>application/x-httpd-cgi</code>''.</li> 1752 1753 <li> 1754 '<strong><code>nosubreq|NS</code></strong>' (used only if 1755 <strong>n</strong>o internal 1756 <strong>s</strong>ub-request)<br /> 1757 This flag forces the rewriting engine to skip a 1758 rewriting rule if the current request is an internal 1759 sub-request. For instance, sub-requests occur internally 1760 in Apache when <code>mod_include</code> tries to find out 1761 information about possible directory default files 1762 (<code>index.xxx</code>). On sub-requests it is not 1763 always useful and even sometimes causes a failure to if 1764 the complete set of rules are applied. Use this flag to 1765 exclude some rules.<br /> 1766 1767 1768 <p>Use the following rule for your decision: whenever you 1769 prefix some URLs with CGI-scripts to force them to be 1770 processed by the CGI-script, the chance is high that you 1771 will run into problems (or even overhead) on 1772 sub-requests. In these cases, use this flag.</p> 1773 </li> 1774 1775 <li>'<strong><code>nocase|NC</code></strong>' 1776 (<strong>n</strong>o <strong>c</strong>ase)<br /> 1777 This makes the <em>Pattern</em> case-insensitive, 1778 <em>i.e.</em>, there is no difference between 'A-Z' and 1779 'a-z' when <em>Pattern</em> is matched against the current 1780 URL.</li> 1781 1782 <li>'<strong><code>qsappend|QSA</code></strong>' 1783 (<strong>q</strong>uery <strong>s</strong>tring 1784 <strong>a</strong>ppend)<br /> 1785 This flag forces the rewriting engine to append a query 1786 string part in the substitution string to the existing one 1787 instead of replacing it. Use this when you want to add more 1788 data to the query string via a rewrite rule.</li> 1789 1790 <li> 1791 '<strong><code>noescape|NE</code></strong>' 1792 (<strong>n</strong>o URI <strong>e</strong>scaping of 1793 output)<br /> 1794 This flag keeps mod_rewrite from applying the usual URI 1795 escaping rules to the result of a rewrite. Ordinarily, 1796 special characters (such as '%', '$', ';', and so on) 1797 will be escaped into their hexcode equivalents ('%25', 1798 '%24', and '%3B', respectively); this flag prevents this 1799 from being done. This allows percent symbols to appear in 1800 the output, as in 1801<pre> 1802 RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE] 1803 1804</pre> 1805 which would turn '<code>/foo/zed</code>' into a safe 1806 request for '<code>/bar?arg=P1=zed</code>'. 1807 1808 <table width="70%" border="0" bgcolor="#E0E0F0" 1809 cellspacing="0" cellpadding="10"> 1810 <tr> 1811 <td><strong>Notice:</strong> The 1812 <code>noescape</code> flag is only available with 1813 Apache 1.3.20 and later versions.</td> 1814 </tr> 1815 </table> 1816 </li> 1817 1818 <li> 1819 '<strong><code>passthrough|PT</code></strong>' 1820 (<strong>p</strong>ass <strong>t</strong>hrough to next 1821 handler)<br /> 1822 This flag forces the rewriting engine to set the 1823 <code>uri</code> field of the internal 1824 <code>request_rec</code> structure to the value of the 1825 <code>filename</code> field. This flag is just a hack to 1826 be able to post-process the output of 1827 <code>RewriteRule</code> directives by 1828 <code>Alias</code>, <code>ScriptAlias</code>, 1829 <code>Redirect</code>, <em>etc.</em> directives from 1830 other URI-to-filename translators. A trivial example to 1831 show the semantics: If you want to rewrite 1832 <code>/abc</code> to <code>/def</code> via the rewriting 1833 engine of <code>mod_rewrite</code> and then 1834 <code>/def</code> to <code>/ghi</code> with 1835 <code>mod_alias</code>: 1836<pre> 1837 RewriteRule ^/abc(.*) /def$1 [PT] 1838 Alias /def /ghi 1839 1840</pre> 1841 If you omit the <code>PT</code> flag then 1842 <code>mod_rewrite</code> will do its job fine, 1843 <em>i.e.</em>, it rewrites <code>uri=/abc/...</code> to 1844 <code>filename=/def/...</code> as a full API-compliant 1845 URI-to-filename translator should do. Then 1846 <code>mod_alias</code> comes and tries to do a 1847 URI-to-filename transition which will not work. 1848 1849 <p>Note: <strong>You have to use this flag if you want to 1850 intermix directives of different modules which contain 1851 URL-to-filename translators</strong>. The typical example 1852 is the use of <code>mod_alias</code> and 1853 <code>mod_rewrite</code>..</p> 1854 </li> 1855 1856 <li>'<strong><code>skip|S</code></strong>=<em>num</em>' 1857 (<strong>s</strong>kip next rule(s))<br /> 1858 This flag forces the rewriting engine to skip the next 1859 <em>num</em> rules in sequence when the current rule 1860 matches. Use this to make pseudo if-then-else constructs: 1861 The last rule of the then-clause becomes 1862 <code>skip=N</code> where N is the number of rules in the 1863 else-clause. (This is <strong>not</strong> the same as the 1864 'chain|C' flag!)</li> 1865 1866 <li> 1867 '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>' 1868 (set <strong>e</strong>nvironment variable)<br /> 1869 This forces an environment variable named <em>VAR</em> to 1870 be set to the value <em>VAL</em>, where <em>VAL</em> can 1871 contain regexp backreferences <code>$N</code> and 1872 <code>%N</code> which will be expanded. You can use this 1873 flag more than once to set more than one variable. The 1874 variables can be later dereferenced in many situations, but 1875 usually from within XSSI (via <code><!--#echo 1876 var="VAR"--></code>) or CGI (<em>e.g.</em> 1877 <code>$ENV{'VAR'}</code>). Additionally you can dereference 1878 it in a following RewriteCond pattern via 1879 <code>%{ENV:VAR}</code>. Use this to strip but remember 1880 information from URLs.</li> 1881 </ul> 1882 1883 <table width="70%" border="0" bgcolor="#E0E0F0" 1884 cellspacing="0" cellpadding="10"> 1885 <tr> 1886 <td> 1887 <strong>Note:</strong> Never forget that 1888 <em>Pattern</em> is applied to a complete URL in 1889 per-server configuration files. <strong>But in 1890 per-directory configuration files, the per-directory 1891 prefix (which always is the same for a specific 1892 directory!) is automatically <em>removed</em> for the 1893 pattern matching and automatically <em>added</em> after 1894 the substitution has been done.</strong> This feature 1895 is essential for many sorts of rewriting, because 1896 without this prefix stripping you have to match the 1897 parent directory which is not always possible. 1898 1899 <p>There is one exception: If a substitution string 1900 starts with ``<code>http://</code>'' then the directory 1901 prefix will <strong>not</strong> be added and an 1902 external redirect or proxy throughput (if flag 1903 <strong>P</strong> is used!) is forced!</p> 1904 </td> 1905 </tr> 1906 </table> 1907 1908 <table width="70%" border="0" bgcolor="#E0E0F0" 1909 cellspacing="0" cellpadding="10"> 1910 <tr> 1911 <td><strong>Note:</strong> To enable the rewriting engine 1912 for per-directory configuration files you need to set 1913 ``<code>RewriteEngine On</code>'' in these files 1914 <strong>and</strong> ``<code>Options 1915 FollowSymLinks</code>'' must be enabled. If your 1916 administrator has disabled override of 1917 <code>FollowSymLinks</code> for a user's directory, then 1918 you cannot use the rewriting engine. This restriction is 1919 needed for security reasons.</td> 1920 </tr> 1921 </table> 1922 1923 <p>Here are all possible substitution combinations and their 1924 meanings:</p> 1925 1926 <p><strong>Inside per-server configuration 1927 (<code>httpd.conf</code>)<br /> 1928 for request ``<code>GET 1929 /somepath/pathinfo</code>'':</strong><br /> 1930 </p> 1931 1932 <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5"> 1933 <tr> 1934 <td> 1935<pre> 1936<strong>Given Rule</strong> <strong>Resulting Substitution</strong> 1937---------------------------------------------- ---------------------------------- 1938^/somepath(.*) otherpath$1 not supported, because invalid! 1939 1940^/somepath(.*) otherpath$1 [R] not supported, because invalid! 1941 1942^/somepath(.*) otherpath$1 [P] not supported, because invalid! 1943---------------------------------------------- ---------------------------------- 1944^/somepath(.*) /otherpath$1 /otherpath/pathinfo 1945 1946^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo 1947 via external redirection 1948 1949^/somepath(.*) /otherpath$1 [P] not supported, because silly! 1950---------------------------------------------- ---------------------------------- 1951^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo 1952 1953^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo 1954 via external redirection 1955 1956^/somepath(.*) http://thishost/otherpath$1 [P] not supported, because silly! 1957---------------------------------------------- ---------------------------------- 1958^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo 1959 via external redirection 1960 1961^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo 1962 via external redirection 1963 (the [R] flag is redundant) 1964 1965^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo 1966 via internal proxy 1967</pre> 1968 </td> 1969 </tr> 1970 </table> 1971 1972 <p><strong>Inside per-directory configuration for 1973 <code>/somepath</code><br /> 1974 (<em>i.e.</em>, file <code>.htaccess</code> in dir 1975 <code>/physical/path/to/somepath</code> containing 1976 <code>RewriteBase /somepath</code>)<br /> 1977 for request ``<code>GET 1978 /somepath/localpath/pathinfo</code>'':</strong><br /> 1979 </p> 1980 1981 <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5"> 1982 <tr> 1983 <td> 1984<pre> 1985<strong>Given Rule</strong> <strong>Resulting Substitution</strong> 1986---------------------------------------------- ---------------------------------- 1987^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo 1988 1989^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo 1990 via external redirection 1991 1992^localpath(.*) otherpath$1 [P] not supported, because silly! 1993---------------------------------------------- ---------------------------------- 1994^localpath(.*) /otherpath$1 /otherpath/pathinfo 1995 1996^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo 1997 via external redirection 1998 1999^localpath(.*) /otherpath$1 [P] not supported, because silly! 2000---------------------------------------------- ---------------------------------- 2001^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo 2002 2003^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo 2004 via external redirection 2005 2006^localpath(.*) http://thishost/otherpath$1 [P] not supported, because silly! 2007---------------------------------------------- ---------------------------------- 2008^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo 2009 via external redirection 2010 2011^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo 2012 via external redirection 2013 (the [R] flag is redundant) 2014 2015^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo 2016 via internal proxy 2017</pre> 2018 </td> 2019 </tr> 2020 </table> 2021 2022 <p><strong>Example:</strong></p> 2023 2024 <blockquote> 2025 We want to rewrite URLs of the form 2026 2027 <blockquote> 2028 <code>/</code> <em>Language</em> <code>/~</code> 2029 <em>Realname</em> <code>/.../</code> <em>File</em> 2030 </blockquote> 2031 into 2032 2033 <blockquote> 2034 <code>/u/</code> <em>Username</em> <code>/.../</code> 2035 <em>File</em> <code>.</code> <em>Language</em> 2036 </blockquote> 2037 2038 <p>We take the rewrite mapfile from above and save it under 2039 <code>/path/to/file/map.txt</code>. Then we only have to 2040 add the following lines to the Apache server configuration 2041 file:</p> 2042 2043 <blockquote> 2044<pre> 2045RewriteLog /path/to/file/rewrite.log 2046RewriteMap real-to-user txt:/path/to/file/map.txt 2047RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1 2048</pre> 2049 </blockquote> 2050 </blockquote> 2051 <hr noshade="noshade" size="1" /> 2052 2053 <center> 2054 <h1><a id="Miscelleneous" 2055 name="Miscelleneous">Miscellaneous</a></h1> 2056 </center> 2057 <hr noshade="noshade" size="1" /> 2058 2059 <h2><a id="EnvVar" name="EnvVar">Environment 2060 Variables</a></h2> 2061 This module keeps track of two additional (non-standard) 2062 CGI/SSI environment variables named <code>SCRIPT_URL</code> 2063 and <code>SCRIPT_URI</code>. These contain the 2064 <em>logical</em> Web-view to the current resource, while the 2065 standard CGI/SSI variables <code>SCRIPT_NAME</code> and 2066 <code>SCRIPT_FILENAME</code> contain the <em>physical</em> 2067 System-view. 2068 2069 <p>Notice: These variables hold the URI/URL <em>as they were 2070 initially requested</em>, <em>i.e.</em>, <em>before</em> any 2071 rewriting. This is important because the rewriting process is 2072 primarily used to rewrite logical URLs to physical 2073 pathnames.</p> 2074 2075 <p><strong>Example:</strong></p> 2076 2077 <blockquote> 2078<pre> 2079SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html 2080SCRIPT_FILENAME=/u/rse/.www/index.html 2081SCRIPT_URL=/u/rse/ 2082SCRIPT_URI=http://en1.engelschall.com/u/rse/ 2083</pre> 2084 </blockquote> 2085 <hr noshade="noshade" size="1" /> 2086 2087 <h2><a id="Solutions" name="Solutions">Practical 2088 Solutions</a></h2> 2089 We also have an <a href="../misc/rewriteguide.html">URL 2090 Rewriting Guide</a> available, which provides a collection of 2091 practical solutions for URL-based problems. There you can 2092 find real-life rulesets and additional information about 2093 mod_rewrite. 2094 </blockquote> 2095 <hr /> 2096 2097 <h3 align="CENTER">Apache HTTP Server Version 1.3</h3> 2098 <a href="./"><img src="../images/index.gif" alt="Index" /></a> 2099 <a href="../"><img src="../images/home.gif" alt="Home" /></a> 2100 2101 <!-- page indentation --> 2102 <!--/%hypertext --> 2103 </body> 2104</html> 2105 2106 2107 2108
