granicus.if.org Git - apache/blob - docs/manual/rewrite/remapping.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision: 832069 $ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <manualpage metafile="remapping.xml.meta">
  24   <parentdocument href="./">Rewrite</parentdocument>
  25
  26 <title>Redirecting and Remapping with mod_rewrite</title>
  27
  28 <summary>
  29
  30 <p>This document supplements the <module>mod_rewrite</module>
  31 <a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
  32 how you can use <module>mod_rewrite</module> to redirect and remap
  33 request. This includes many examples of common uses of mod_rewrite,
  34 including detailed descriptions of how each works.</p>
  35
  36 <note type="warning">Note that many of these examples won't work unchanged in your
  37 particular server configuration, so it's important that you understand
  38 them, rather than merely cutting and pasting the examples into your
  39 configuration.</note>
  40
  41 </summary>
  42 <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
  43 <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
  44 <!-- <seealso><a href="remapping.html">Redirection and remapping</a></seealso> -->
  45 <seealso><a href="access.html">Controlling access</a></seealso>
  46 <seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>
  47 <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
  48
  49 <section id="old-to-new">
  50
  51   <title>From Old to New (internal)</title>
  52
  53   <dl>
  54     <dt>Description:</dt>
  55
  56     <dd>
  57       <p>Assume we have recently renamed the page
  58       <code>foo.html</code> to <code>bar.html</code> and now want
  59       to provide the old URL for backward compatibility. However,
  60       we want that users of the old URL even not recognize that
  61       the pages was renamed - that is, we don't want the address to
  62       change in their browser.</p>
  63     </dd>
  64
  65     <dt>Solution:</dt>
  66
  67     <dd>
  68       <p>We rewrite the old URL to the new one internally via the
  69       following rule:</p>
  70
  71 <example><pre>
  72 RewriteEngine  on
  73 RewriteRule    ^<strong>/old</strong>\.html$  <strong>/new</strong>.html [PT]
  74 </pre></example>
  75     </dd>
  76   </dl>
  77
  78 </section>
  79
  80 <section id="old-to-new-extern">
  81
  82   <title>Rewriting From Old to New (external)</title>
  83
  84   <dl>
  85     <dt>Description:</dt>
  86
  87     <dd>
  88       <p>Assume again that we have recently renamed the page
  89       <code>foo.html</code> to <code>bar.html</code> and now want
  90       to provide the old URL for backward compatibility. But this
  91       time we want that the users of the old URL get hinted to
  92       the new one, i.e. their browsers Location field should
  93       change, too.</p>
  94     </dd>
  95
  96     <dt>Solution:</dt>
  97
  98     <dd>
  99       <p>We force a HTTP redirect to the new URL which leads to a
 100       change of the browsers and thus the users view:</p>
 101
 102 <example><pre>
 103 RewriteEngine  on
 104 RewriteRule    ^<strong>/foo</strong>\.html$  <strong>bar</strong>.html  [<strong>R</strong>]
 105 </pre></example>
 106 </dd>
 107
 108 <dt>Discussion</dt>
 109
 110     <dd>
 111     <p>In this example, as contrasted to the <a
 112     href="#old-to-new-intern">internal</a> example above, we can simply
 113     use the Redirect directive. mod_rewrite was used in that earlier
 114     example in order to hide the redirect from the client:</p>
 115
 116     <example>
 117     Redirect /foo.html /bar.html
 118     </example>
 119
 120     </dd>
 121   </dl>
 122
 123 </section>
 124
 125 <section id="movehomedirs">
 126
 127   <title>Resource Moved to Another Server</title>
 128
 129   <dl>
 130     <dt>Description:</dt>
 131
 132     <dd>
 133       <p>If a resource has moved to another server, you may wish to have
 134       URLs continue to work for a time on the old server while people
 135       update their bookmarks.</p>
 136     </dd>
 137
 138     <dt>Solution:</dt>
 139
 140     <dd>
 141       <p>You can use <module>mod_rewrite</module> to redirect these URLs
 142       to the new server, but you might also consider using the Redirect
 143       or RedirectMatch directive.</p>
 144
 145 <example><title>With mod_rewrite</title><pre>
 146 RewriteEngine on
 147 RewriteRule   ^/docs/(.+)  http://new.example.com/docs/$1  [R,L]
 148 </pre></example>
 149
 150 <example><title>With RedirectMatch</title><pre>
 151 RedirectMatch ^/docs/(.*) http://new.example.com/docs/$1
 152 </pre></example>
 153
 154 <example><title>With Redirect</title><pre>
 155 Redirect /docs/ http://new.example.com/docs/
 156 </pre></example>
 157     </dd>
 158   </dl>
 159
 160 </section>
 161
 162 <section id="static-to-dynamic">
 163
 164   <title>From Static to Dynamic</title>
 165
 166   <dl>
 167     <dt>Description:</dt>
 168
 169     <dd>
 170       <p>How can we transform a static page
 171       <code>foo.html</code> into a dynamic variant
 172       <code>foo.cgi</code> in a seamless way, i.e. without notice
 173       by the browser/user.</p>
 174     </dd>
 175
 176     <dt>Solution:</dt>
 177
 178     <dd>
 179       <p>We just rewrite the URL to the CGI-script and force the
 180       handler to be <strong>cgi-script</strong> so that it is
 181       executed as a CGI program.
 182       This way a request to <code>/~quux/foo.html</code>
 183       internally leads to the invocation of
 184       <code>/~quux/foo.cgi</code>.</p>
 185
 186 <example><pre>
 187 RewriteEngine  on
 188 RewriteBase    /~quux/
 189 RewriteRule    ^foo\.<strong>html</strong>$  foo.<strong>cgi</strong>  [H=<strong>cgi-script</strong>]
 190 </pre></example>
 191     </dd>
 192   </dl>
 193
 194 </section>
 195
 196 <section id="backward-compatibility">
 197
 198   <title>Backward Compatibility for file extension change</title>
 199
 200   <dl>
 201     <dt>Description:</dt>
 202
 203     <dd>
 204       <p>How can we make URLs backward compatible (still
 205       existing virtually) after migrating <code>document.YYYY</code>
 206       to <code>document.XXXX</code>, e.g. after translating a
 207       bunch of <code>.html</code> files to <code>.php</code>?</p>
 208     </dd>
 209
 210     <dt>Solution:</dt>
 211
 212     <dd>
 213       <p>We rewrite the name to its basename and test for
 214       existence of the new extension. If it exists, we take
 215       that name, else we rewrite the URL to its original state.</p>
 216
 217 <example><pre>
 218 #   backward compatibility ruleset for
 219 #   rewriting document.html to document.php
 220 #   when and only when document.php exists
 221 &lt;Directory /var/www/htdocs&gt;
 222 RewriteEngine on
 223 RewriteBase /var/www/htdocs
 224
 225 RewriteCond $1.php -f
 226 RewriteCond $1.html !-f
 227 RewriteRule ^(.*).html$ $1.php
 228 &lt;/Directory&gt;
 229 </pre></example>
 230     </dd>
 231
 232     <dt>Discussion</dt>
 233     <dd>
 234     <p>This example uses an often-overlooked feature of mod_rewrite,
 235     by taking advantage of the order of execution of the ruleset. In
 236     particular, mod_rewrite evaluates the left-hand-side of the
 237     RewriteRule before it evaluates the RewriteCond directives.
 238     Consequently, $1 is already defined by the time the RewriteCond
 239     directives are evaluated. This allows us to test for the existence
 240     of the original (<code>document.html</code>) and target
 241     (<code>document.php</code>) files using the same base filename.</p>
 242
 243     <p>This ruleset is designed to use in a per-directory context (In a
 244     &lt;Directory&gt; block or in a .htaccess file), so that the
 245     <code>-f</code> checks are looking at the correct directory path.
 246     You may need to set a <directive
 247     module="mod_rewite">RewriteBase</directive> directive to specify the
 248     directory base that you're working in.</p>
 249     </dd>
 250   </dl>
 251
 252 </section>
 253
 254 <section id="canonicalhost">
 255
 256 <title>Canonical Hostnames</title>
 257
 258       <dl>
 259         <dt>Description:</dt>
 260
 261         <dd>The goal of this rule is to force the use of a particular
 262         hostname, in preference to other hostnames which may be used to
 263         reach the same site. For example, if you wish to force the use
 264         of <strong>www.example.com</strong> instead of
 265         <strong>example.com</strong>, you might use a variant of the
 266         following recipe.</dd>
 267
 268         <dt>Solution:</dt>
 269
 270         <dd>
 271 <p>For sites running on a port other than 80:</p>
 272 <example><pre>
 273 RewriteCond %{HTTP_HOST}   !^www\.example\.com [NC]
 274 RewriteCond %{HTTP_HOST}   !^$
 275 RewriteCond %{SERVER_PORT} !^80$
 276 RewriteRule ^/?(.*)         http://www.example.com:%{SERVER_PORT}/$1 [L,R,NE]
 277 </pre></example>
 278
 279 <p>And for a site running on port 80</p>
 280 <example><pre>
 281 RewriteCond %{HTTP_HOST}   !^www\.example\.com [NC]
 282 RewriteCond %{HTTP_HOST}   !^$
 283 RewriteRule ^/?(.*)         http://www.example.com/$1 [L,R,NE]
 284 </pre></example>
 285
 286         <p>
 287         If you wanted to do this generically for all domain names - that
 288         is, if you want to redirect <strong>example.com</strong> to
 289         <strong>www.example.com</strong> for all possible values of
 290         <strong>example.com</strong>, you could use the following
 291         recipe:</p>
 292
 293 <example><pre>
 294 RewriteCond %{HTTP_HOST} !^www\. [NC]
 295 RewriteCond %{HTTP_HOST} !^$
 296 RewriteRule ^/?(.*) http://www.%{HTTP_HOST}/$1 [L,R,NE]
 297 </pre></example>
 298
 299     <p>These rulesets will work either in your main server configuration
 300     file, or in a <code>.htaccess</code> file placed in the <directive
 301     module="core">DocumentRoot</directive> of the server.</p>
 302         </dd>
 303       </dl>
 304
 305 </section>
 306
 307 <section id="multipledirs">
 308
 309   <title>Search for pages in more than one directory</title>
 310
 311   <dl>
 312     <dt>Description:</dt>
 313
 314     <dd>
 315       <p>A particular resource might exist in one of several places, and
 316       we want to look in those places for the resource when it is
 317       requested. Perhaps we've recently rearranged our directory
 318       structure, dividing content into several locations.</p>
 319     </dd>
 320
 321     <dt>Solution:</dt>
 322
 323     <dd>
 324       <p>The following ruleset searches in two directories to find the
 325       resource, and, if not finding it in either place, will attempt to
 326       just serve it out of the location requested.</p>
 327
 328 <example><pre>
 329 RewriteEngine on
 330
 331 #   first try to find it in dir1/...
 332 #   ...and if found stop and be happy:
 333 RewriteCond         %{DOCUMENT_ROOT}/<strong>dir1</strong>/%{REQUEST_URI}  -f
 334 RewriteRule  ^(.+)  %{DOCUMENT_ROOT}/<strong>dir1</strong>/$1  [L]
 335
 336 #   second try to find it in dir2/...
 337 #   ...and if found stop and be happy:
 338 RewriteCond         %{DOCUMENT_ROOT}/<strong>dir2</strong>/%{REQUEST_URI}  -f
 339 RewriteRule  ^(.+)  %{DOCUMENT_ROOT}/<strong>dir2</strong>/$1  [L]
 340
 341 #   else go on for other Alias or ScriptAlias directives,
 342 #   etc.
 343 RewriteRule   ^(.+)  -  [PT]
 344 </pre></example>
 345     </dd>
 346   </dl>
 347
 348 </section>
 349
 350 <section id="archive-access-multiplexer">
 351
 352   <title>Redirecting to Geographically Distributed Servers</title>
 353
 354   <dl>
 355     <dt>Description:</dt>
 356
 357     <dd>
 358     <p>We have numerous mirrors of our website, and want to redirect
 359     people to the one that is located in the country where they are
 360     located.</p>
 361     </dd>
 362
 363     <dt>Solution:</dt>
 364
 365     <dd>
 366     <p>Looking at the hostname of the requesting client, we determine
 367     which country they are coming from. If we can't do a lookup on their
 368     IP address, we fall back to a default server.</p>
 369     <p>We'll use a <directive module="mod_rewrite">RewriteMap</directive>
 370     directive to build a list of servers that we wish to use.</p>
 371
 372 <example><pre>
 373 HostnameLookups on
 374 RewriteEngine on
 375 RewriteMap    multiplex         txt:/path/to/map.mirrors
 376 RewriteCond  %{REMOTE_HOST}     ([a-z]+)$ [NC]
 377 RewriteRule   ^/(.*)$  ${multiplex:<strong>%1</strong>|http://www.example.com/}$1  [R,L]
 378 </pre></example>
 379
 380 <example><pre>
 381 ##  map.mirrors -- Multiplexing Map
 382
 383 de        http://www.example.de/
 384 uk        http://www.example.uk/
 385 com       http://www.example.com/
 386 ##EOF##
 387 </pre></example>
 388     </dd>
 389
 390     <dt>Discussion</dt>
 391     <dd>
 392     <note type="warning">This ruleset relies on
 393     <directive module="core">HostNameLookups</directive>
 394     being set <code>on</code>, which can be
 395     a significant performance hit.</note>
 396
 397     <p>The <directive module="mod_rewrite">RewriteCond</directive>
 398     directive captures the last portion of the hostname of the
 399     requesting client - the country code - and the following RewriteRule
 400     uses that value to look up the appropriate mirror host in the map
 401     file.</p>
 402     </dd>
 403   </dl>
 404
 405 </section>
 406
 407 <section id="browser-dependent-content">
 408
 409   <title>Browser Dependent Content</title>
 410
 411   <dl>
 412     <dt>Description:</dt>
 413
 414     <dd>
 415       <p>We wish to provide different content based on the browser, or
 416       user-agent, which is requesting the content.</p>
 417     </dd>
 418
 419     <dt>Solution:</dt>
 420
 421     <dd>
 422       <p>We have to decide, based on the HTTP header "User-Agent",
 423       which content to serve. The following config
 424       does the following: If the HTTP header "User-Agent"
 425       contains "Mozilla/3", the page <code>foo.html</code>
 426       is rewritten to <code>foo.NS.html</code> and the
 427       rewriting stops. If the browser is "Lynx" or "Mozilla" of
 428       version 1 or 2, the URL becomes <code>foo.20.html</code>.
 429       All other browsers receive page <code>foo.32.html</code>.
 430       This is done with the following ruleset:</p>
 431
 432 <example><pre>
 433 RewriteCond %{HTTP_USER_AGENT}  ^<strong>Mozilla/3</strong>.*
 434 RewriteRule ^foo\.html$         foo.<strong>NS</strong>.html          [<strong>L</strong>]
 435
 436 RewriteCond %{HTTP_USER_AGENT}  ^<strong>Lynx/</strong>.*         [OR]
 437 RewriteCond %{HTTP_USER_AGENT}  ^<strong>Mozilla/[12]</strong>.*
 438 RewriteRule ^foo\.html$         foo.<strong>20</strong>.html          [<strong>L</strong>]
 439
 440 RewriteRule ^foo\.html$         foo.<strong>32</strong>.html          [<strong>L</strong>]
 441 </pre></example>
 442     </dd>
 443   </dl>
 444
 445 </section>
 446
 447 <section id="canonicalurl">
 448
 449 <title>Canonical URLs</title>
 450
 451 <dl>
 452  <dt>Description:</dt>
 453
 454    <dd>
 455      <p>On some webservers there is more than one URL for a
 456      resource. Usually there are canonical URLs (which are be
 457      actually used and distributed) and those which are just
 458      shortcuts, internal ones, and so on. Independent of which URL the
 459      user supplied with the request, they should finally see the
 460      canonical one in their browser address bar.</p>
 461    </dd>
 462
 463    <dt>Solution:</dt>
 464
 465      <dd>
 466        <p>We do an external HTTP redirect for all non-canonical
 467        URLs to fix them in the location view of the Browser and
 468        for all subsequent requests. In the example ruleset below
 469        we replace <code>/puppies</code> and <code>/canines</code>
 470        by the canonical <code>/dogs</code>.</p>
 471
 472 <example><pre>
 473 RewriteRule   ^/(puppies|canines)/(.*)    /dogs/$2  [R]
 474 </pre></example>
 475         </dd>
 476
 477      <dt>Discussion:</dt>
 478      <dd>
 479      This should really be accomplished with Redirect or RedirectMatch
 480      directives:
 481
 482      <example><pre>
 483      RedirectMatch ^/(puppies|canines)/(.*) /dogs/$2
 484      </pre></example>
 485      </dd>
 486       </dl>
 487
 488 </section>
 489
 490 <section id="uservhosts">
 491
 492   <title>Virtual Hosts Per User</title>
 493
 494   <dl>
 495     <dt>Description:</dt>
 496
 497     <dd>
 498     <p>We want to automatically create a virtual host for every user who
 499     has an account on our web server system, without having to create
 500     new VirtualHost sections.</p>
 501
 502     <p>In this recipe, we assume that we'll be using the hostname
 503     <code>www.<strong>username</strong>.example.com</code> for each
 504     user, and serve their content out of
 505     <code>/home/<strong>username</strong>/www</code>.</p>
 506     </dd>
 507
 508     <dt>Solution:</dt>
 509
 510     <dd>
 511
 512 <example><pre>
 513 RewriteEngine on
 514 RewriteCond   %{<strong>HTTP_HOST</strong>}        ^www\.<strong>([^.]+)</strong>\.example\.com$
 515 RewriteRule   ^(.*) /home/<strong>%1</strong>/www$1
 516 </pre></example></dd>
 517
 518 <dt>Discussion</dt>
 519     <dd>
 520
 521     <note type="warning">You will need to take care of the DNS
 522     resolution - Apache does
 523     not handle name resolution. You'll need either to create CNAME
 524     records for each hostname, or a DNS wildcard record. Creating DNS
 525     records is beyond the scope of this document.</note>
 526
 527 <p>Parentheses used in a <directive
 528 module="mod_rewrite">RewriteCond</directive> are captured into the
 529 backreferences <code>%1</code>, <code>%2</code>, etc, while parentheses
 530 used in <directive module="mod_rewrite">RewriteRule</directive> are
 531 captured into the backreferences <code>$1</code>, <code>$2</code>,
 532 etc.</p>
 533
 534 <p>
 535 As with many techniques discussed in this document, mod_rewrite really
 536 isn't the best way to accomplish this task. You should, instead,
 537 consider using <module>mod_vhost_alias</module> instead, as it will much
 538 more gracefully handle anything beyond serving static files, such as any
 539 dynamic content, and Alias resolution.
 540 </p>
 541     </dd>
 542   </dl>
 543
 544 </section>
 545
 546 <section id="moveddocroot">
 547
 548   <title>Moved <code>DocumentRoot</code></title>
 549
 550   <dl>
 551     <dt>Description:</dt>
 552
 553     <dd>
 554 <p>Usually the <directive module="core">DocumentRoot</directive>
 555 of the webserver directly relates to the URL "<code>/</code>".
 556 But often this data is not really of top-level priority. For example,
 557 you may wish for visitors, on first entering a site, to go to a
 558 particular subdirectory <code>/about/</code>. This may be accomplished
 559 using the following ruleset:</p>
 560 </dd>
 561
 562     <dt>Solution:</dt>
 563
 564     <dd>
 565       <p>We redirect the URL <code>/</code> to
 566       <code>/about/</code>:
 567       </p>
 568
 569 <example><pre>
 570 RewriteEngine on
 571 RewriteRule   <strong>^/$</strong>  /about/  [<strong>R</strong>]
 572 </pre></example>
 573
 574 <p>Note that this can also be handled using the <directive
 575 module="mod_alias">RedirectMatch</directive> directive:</p>
 576
 577 <example>
 578 RedirectMatch ^/$ http://example.com/about/
 579 </example>
 580
 581 <p>Note also that the example rewrites only the root URL. That is, it
 582 rewrites a request for <code>http://example.com/</code>, but not a
 583 request for <code>http://example.com/page.html</code>. If you have in
 584 fact changed your document root - that is, if <strong>all</strong> of
 585 your content is in fact in that subdirectory, it is greatly preferable
 586 to simply change your <directive module="core">DocumentRoot</directive>
 587 directive, or move all of the content up one directory,
 588 rather than rewriting URLs.</p>
 589 </dd>
 590 </dl>
 591
 592 </section>
 593
 594 <section id="fallback-resource">
 595 <title>Fallback Resource</title>
 596
 597 <dl>
 598 <dt>Description:</dt>
 599 <dd>You want a single resource (say, a certain file, like index.php) to
 600 handle all requests that come to a particular directory, except those
 601 that should go to an existing resource such as an image, or a css file.</dd>
 602
 603 <dt>Solution:</dt>
 604 <dd>
 605 <p>As of version 2.4, you should use the <directive
 606 module="mod_dir">FallbackResource</directive> directive for this:</p>
 607
 608 <example>
 609 <pre>
 610 &lt;Directory /var/www/my_blog&gt;
 611   FallbackResource index.php
 612 &lt;/Directory&gt;
 613 </pre>
 614 </example>
 615
 616 <p>However, in earlier versions of Apache, or if your needs are more
 617 complicated than this, you can use a variation of the following rewrite
 618 set to accomplish the same thing:</p>
 619
 620 <example>
 621 <pre>
 622 &lt;Directory /var/www/my_blog&gt;
 623   RewriteBase /my_blog
 624
 625   RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-f
 626   RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-d
 627   RewriteRule ^ index.php [PT]
 628 &lt;/Directory&gt;
 629 </pre>
 630 </example>
 631
 632 <p>If, on the other hand, you wish to pass the requested URI as a query
 633 string argument to index.php, you can replace that RewriteRule with:</p>
 634
 635 <example>
 636 <pre>
 637   RewriteRule (.*) index.php?$1 [PT,QSA]
 638 </pre>
 639 </example>
 640
 641 <p>Note that these rulesets can be uses in a <code>.htaccess</code>
 642 file, as well as in a &lt;Directory&gt; block.</p>
 643
 644 </dd>
 645
 646 </dl>
 647
 648 </section>
 649
 650 <section id="mass-virtual-hosting">
 651
 652   <title>Mass Virtual Hosting</title>
 653
 654   <dl>
 655     <dt>Description:</dt>
 656
 657     <dd>
 658       <p>Mass virtual hosting is one of the more common uses of
 659       mod_rewrite. However, it is seldom the best way to handle mass
 660       virtual hosting. This topic is discussed at great length in the <a
 661       href="../vhosts/mass.html">virtual host documentation</a>.</p>
 662     </dd>
 663   </dl>
 664
 665 </section>
 666
 667 <section id="dynamic-proxy">
 668
 669   <title>Proxying Content with mod_rewrite</title>
 670
 671   <dl>
 672     <dt>Description:</dt>
 673
 674     <dd>
 675     <p>
 676     mod_rewrite provides the [P] flag, which allows URLs to be passed,
 677     via mod_proxy, to another server. Two examples are given here. In
 678     one example, a URL is passed directly to another server, and served
 679     as though it were a local URL. In the other example, we proxy
 680     missing content to a back-end server.</p>
 681     </dd>
 682
 683     <dt>Solution:</dt>
 684
 685     <dd>
 686       <p>To simply map a URL to another server, we use the [P] flag, as
 687       follows:</p>
 688
 689 <example><pre>
 690 RewriteEngine  on
 691 RewriteBase    /products/
 692 RewriteRule    ^<strong>widget/</strong>(.*)$  <strong>http://product.example.com/widget/</strong>$1  [<strong>P</strong>]
 693 ProxyPassReverse /products/widget/ http://product.example.com/widget/
 694 </pre></example>
 695
 696    <p>In the second example, we proxy the request only if we can't find
 697    the resource locally. This can be very useful when you're migrating
 698    from one server to another, and you're not sure if all the content
 699    has been migrated yet.</p>
 700
 701 <example><pre>
 702 RewriteCond %{REQUEST_FILENAME}       <strong>!-f</strong>
 703 RewriteCond %{REQUEST_FILENAME}       <strong>!-d</strong>
 704 RewriteRule ^/(.*) http://<strong>old</strong>.example.com$1 [<strong>P</strong>]
 705 ProxyPassReverse / http://old.example.com/
 706 </pre></example>
 707     </dd>
 708
 709     <dt>Discussion:</dt>
 710
 711     <dd><p>In each case, we add a <directive
 712     module="mod_proxy">ProxyPassReverse</directive> directive to ensure
 713     that any redirects issued by the backend are correctly passed on to
 714     the client.</p>
 715
 716     <p>Consider using either <directive
 717     module="mod_proxy">ProxyPass</directive> or <directive
 718     module="mod_rewrite">ProxyPassMatch</directive> whenever possible in
 719     preference to mod_rewrite.</p>
 720     </dd>
 721   </dl>
 722
 723 </section>
 724
 725 </manualpage>