mod_proxy_html

mod_proxy_html is an output filter to rewrite HTML links in a proxy situation, to ensure that links work for users outside the proxy. It serves the same purpose as Apache's ProxyPassReverse directive does for HTTP headers, and is an essential component of a reverse proxy.

For example, if a company has an application server at appserver.example.com that is only visible from within the company's internal network, and a public webserver www.example.com, they may wish to provide a gateway to the application server at http://www.example.com/appserver/. When the application server links to itself, those links need to be rewritten to work through the gateway. mod_proxy_html serves to rewrite <a href="http://appserver.example.com/foo/bar.html">foobar</a> to <a href="http://www.example.com/appserver/foo/bar.html">foobar</a> making it accessible from outside.

April 2006 Added a new FAQ to deal with some of the questions people commonly mail me with.

Origins and History

The current bugfix release is 3.1.2, which has no functional changes but has been fixed to compile successfully on Windows/MSVC++. The previous version 3.1.1 fixes a bug parsing <META> elements with ProxyHTMLMeta documented here.

The current version is 3.1. This builds on the new features in 3.0, but delegates internationalisation/charset support to mod_xml2enc. The previous version 3.0 is here.

The origins and history of mod_proxy_html are documented in a separate page.

Related Modules

mod_proxy_html is derived originally from mod_accessibility.
A companion module mod_proxy_xml serves a similar purpose for XML document types, based on extensible namespace processing.
mod_publisher is the universal markup manipulation filter. It includes the capabilities of mod_proxy_html amongst a broad range of powerful markup processing options.
mod_xml2enc provides extensive internationalisation support for mod_proxy_html. In the absence of mod_xml2enc, mod_proxy_html will work well on ASCII or UTF-8 (Unicode), but may display other character sets incorrectly (or not at all).

Capabilities

The original capabilities of mod_proxy_html are:

Parses HTML and XHTML markup, rewriting links according to rules defined by the server admin.
Optionally converts HTML to XHTML or vice versa.
Optionally makes some minor corrections to broken HTML.

Important changes from 1.x to 2.x include:

Support for rewriting URLs in scripts, stylesheets and scripting events
Support for regular expression match-and-replace
Improved charset detection, including XML BOM, XML declaration, and HTML META where the information is not available in HTTP.
Support for converting meta http-equiv HTML elements to real HTTP headers.
The default FPI (doctype) generated has changed to none, on the grounds that it's better to omit it than declare a bogus doctype. You should now configure it explicitly if your backend generates sane HTML or XHTML.
A verbose logging option is provided to help with testing your configuration and diagnosing exactly what it is doing.

Important changes from 2.x to 3.x include:

Improved Internationalisation support no longer relies on libxml2's useful but limited builtin capabilities, but is delegated to mod_xml2enc.
Configurable support for proprietary HTML variants.
Enables fixups for bad HTML, including corrections and workarounds for common problems.
Flexible configuration using environment variables, interpolation, and conditional execution of rules.

With these new features, mod_proxy_html might find applications outside a proxy context, and an environment variable PROXY_HTML_FORCE can be used to force it to process non-proxied pages. But reverse-proxying remains its primary purpose, while mod_publisher offers a far wider range of capabilities for other applications.

How to use it

Important Note: Configuration has changed:

Unless you only need to handle unicode (or ASCII), you should load mod_xml2enc alongside mod_proxy_html.
Instead of using Apache's filter configuration directives, use the new ProxyHTMLEnable directive, and mod_proxy_html will configure both itself and mod_xml2enc for you.

We now have three documents: a tutorial on reverse proxying (including basic use of mod_proxy_html), a user guide, and a configuration guide. Please read the tutorial first, unless you already know it all!

Tutorial: Reverse Proxying

A tutorial on reverse proxying with Apache by the author of this module is available at ApacheTutor. This offers an in-depth overview of the problem solved by this module, in context.

Configuration Guide

Reference documentation for the configuration directives implemented by mod_proxy_html.

Technical Guide

This focuses on the module itself, separate from the context of the problem it solves.

Frequently Asked Questions

Some questions come up repeatedly (sometimes in the form of bug reports, feature requests, or patches). Please see the FAQ before mailing anything.

Support

Please don't just email with support questions. If you need more help than is provided in the documentation, you may register for support. If you don't want to register, you may also ask questions in a public forum such as the apache users mailinglist, where your question and any responses will be on record for others to see.

Availability

mod_proxy_html.c source code is available under the GNU General Public License (GPL) Version 2. As with other opensource modules, we can consider alternative licenses by request.

Current Version (3.1.2) as bzipped tar (signature) and as zipfile (signature).
Development Version.

NOTE: If you downloaded the bundle before October 30th, you should upgrade your copy of mod_xml2enc to 1.0.3, which fixes a bug. The current bundle includes the bugfix.

Registered Users may request binaries for any available platform: there is no charge to upgrade from earlier versions. Since April 2004, binaries have been supplied to registered users for Linux, FreeBSD, Windows, Solaris and MacOSX. If you need it for another platform, please ask.

Errata

Users of the FreeBSD port of mod_proxy_html, please see this fix.