mod_proxy_html.html

   1 <?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   2 <html lang="en"><head>
   3 <title>mod_proxy_html</title>
   4 <style type="text/css">
   5 @import url(/index.css) ;
   6 </style>
   7 </head><body>
   8 <div id="apache">
   9 <h1><a href="./">mod_proxy_html</a></h1>
  10 <div class="notice">
  11 <h2>Notice</h2>
  12 <p>Users of mod_proxy_html should upgrade to <a href="http://xmlsoft.org/">libxml2 version 2.5.10</a> or later.
  13 This fixes bugs in earlier versions that
  14 can in some cases have a severe impact on performance.</p>
  15 </div>
  16
  17 <p>mod_proxy_html is based on one specific capability of
  18 <a href="../mod_accessibility/">mod_accessibility</a>, namely that of
  19 rewriting HTML links so that they don't break in a reverse proxy.
  20 The need for it was identified in <a href="http://groups.google.com/groups?dq=&amp;hl=en&amp;lr=&amp;ie=UTF-8&amp;th=f71d3dfe32c6387f&amp;seekm=slrnbhi6p4.4pb.wizball%40babar.foo.com&amp;frame=off">a Usenet thread</a>.</p>
  21 <p>The problem arises when links such as <code>&lt;a
  22 href="http://private-address.example.com/"></code> are used in
  23 a proxied page, when the server <code>private-address.example.com</code>
  24 needs to be proxied (for example, because its address is not valid
  25 beyond a private network).  <code>mod_proxy_html</code> rewrites
  26 such URLs into the proxy's own namespace.</p>
  27 <p>The key directive required for this is <tt>ProxyHTMLURLMap</tt>.
  28 This is functionally identical to <tt>AccessibilityURLMap</tt>,
  29 which is documented in the
  30 <a href="../mod_accessibility/">mod_accessibility</a> pages.</p>
  31 <h3>Example: how to use it</h3>
  32 <p>In this case, the proxy is serving pages from two internal servers
  33 <tt>internal.example.org</tt> and <tt>other.example.org</tt>
  34 neither of which is accessible directly from the outside world.
  35 The directives for this are:</p>
  36 <dl>
  37 <dt><code>ProxyPass     /internal.example.org/  http://internal.example.org/</code>
  38 <br/><code>ProxyPass    /other.example.org/     http://other.example.org/</code>
  39 <dd>Map the URLs to the proxy's address space, as documented in Apache's
  40 <tt>mod_proxy</tt> documentation.</dd>
  41 <dt><code>ProxyHTMLURLMap       http://internal.example.org     /internal.example.org</code>
  42 <br/><code>ProxyHTMLURLMap      http://other.example.org        /other.example.org</code></dt>
  43 <dd>This causes mod_proxy_html to rewrite all absolute URLs for
  44 the internal domains to the proxy's address space.  These directives
  45 <em>could</em> go inside the Location directives below, but putting them
  46 at top level saves repeating them at different Locations.
  47 <strong>NOTE:</strong> because the pattern matching used is starts-with,
  48 it is best to omit any trailing slash from the above URL.
  49 </dd>
  50 <dt><code>&lt;Location  /internal.example.org/></code></dt>
  51 <dd>Specifies directives that will apply (only) under
  52 <tt>/internal.example.org</tt></dd>
  53 <dt><code>ProxyPassReverse      /</code></dt>
  54 <dd>Rewrite URLs in HTTP Headers (mod_proxy)</dd>
  55 <dt><code>SetOutputFilter       proxy-html</code></dt>
  56 <dd>Inserts (activates) the proxy-html output filter</dd>
  57 <dt><code>ProxyHTMLURLMap       /       /internal.example.org/</code></dt>
  58 <dd>Rewrites URLs starting with a <tt>/</tt> into the proxy's address space.</dd>
  59 <dt><code>ProxyHTMLURLMap       /internal.example.org/  /internal.example.org/</code></dt>
  60 <dd>This is necessary to prevent the previous rule rewriting relative URLs
  61 already in the Proxy's address space.  It must come after the previous rule.</dd>
  62 <dt><code>&lt;/Location></code></dt>
  63 <dd>Ends directives for <tt>/internal.example.org</tt>.  Equivalent directives
  64 are of course also required for <tt>/other.example.org</tt>, but are
  65 omitted (for brevity) from this page.</dd>
  66 </dl>
  67 <h2>Availability</h2>
  68 <p><a href="mod_proxy_html.c">mod_proxy_html.c source code</a> is available
  69 under the <a href="http://www.fsf.org/licenses/gpl.html">GNU
  70 General Public License (GPL)</a>.  As with other opensource modules,
  71 we can consider alternative licenses by request.</p>
  72 </div>
  73 <div id="navbar"><a class="internal" href="./" title="Up">Up</a>
  74 *
  75 <a class="internal" href="/" title="WebThing Apache Centre">Home</a>
  76 *
  77 <a class="internal" href="/contact.html" title="Contact WebThing">Contact</a>
  78 *
  79 <a class="external" href="http://www.webthing.com/" title="WebThing Ltd">WebÞing</a>
  80 *
  81 <a class="external" href="http://www.apache.org/" title="Apache Software Foundation">Apache</a></div></body></html>