Apache Module mod_proxy_html

This module provides 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. modproxyhtml serves to rewrite foobar

making it accessible from outside.

modproxyhtml was originally developed at WebŞing, whose extensive documentation may be useful to users.

The default is 8192, and will work well for almost all pages. However, if you know you're proxying pages containing stylesheets and/or scripts bigger than 8K (that is, for a single script or stylesheet, NOT in total), it will be more efficient to set a larger buffer size and avoid the need to resize the buffer dynamically during a request.

ProxyHTMLDocType fpi [SGML|XML]

In the first form, documents will be declared as HTML 4.01 or XHTML 1.0 according to the option selected. This option also determines whether HTML or XHTML syntax is used for output. Note that the format of the documents coming from the backend server is immaterial: the parser will deal with it automatically. If the optional second argument is set to "Legacy", documents will be declared "Transitional", an option that may be necessary if you are proxying pre-1998 content or working with defective authoring/publishing tools.

The default is changed to omitting any FPI, on the grounds that no FPI is better than a bogus one. If your backend generates decent HTML or XHTML, set it accordingly.

If the first form is used, modproxyhtml will also clean up the HTML to the specified standard. It cannot fix every error, but it will strip out bogus elements and attributes. It will also optionally log other errors at

Note that the proxyhtml filter will only act on HTML data (Content-Type text/html or application/xhtml+xml) and when the data are proxied. You can override this (at your own risk) by setting the PROXYHTML_FORCE environment variable.

Normally you'll set this globally. If you set ProxyHTMLEvents in more than one scope so that one overrides the other, you'll need to specify a complete set in each of those scopes.

A default configuration is supplied in proxy-html.conf and defines the events in standard HTML 4 and XHTML 1.

rules, according to the flags set for each rule. Since this requires more parsing, performance will be best if you only enable it when strictly necessary.

You'll also need to take care over patterns matched, since the parser has no knowledge of what is a URL within an embedded script or stylesheet. In particular, extended matching of /

is likely to lead to false matches.

ProxyHTMLFixups [lowercase] [dospath] [reset]

Urls are rewritten to lowercasedospath

Backslashes in URLs are rewritten to forward slashes.reset

Unset any options set at a higher level in the configuration.Take care when using these. The fixes will correct certain authoring mistakes, but risk also erroneously fixing links that were correct to start with. Only use them if you know you have a broken backend server.

If interpolation is not enabled, all rules are pre-compiled at startup. With interpolation, they must be re-compiled for every request, which implies an extra processing overhead. It should therefore be enabled only when necessary.

ProxyHTMLLinks element attribute [attribute2 ...]

If not required, turning ProxyHTMLMeta Off will give a small performance boost by skipping this parse step. However, it is sometimes necessary for internationalisation to work correctly.

ProxyHTMLMeta has two effects. Firstly and most importantly it enables detection of character encodings declared in the form

or, in the case of an XHTML document, an XML declaration. It is NOT required if the charset is declared in a real HTTP header (which is always preferable) from the backend server, nor if the document is utf-8 (unicode) or a subset such as ASCII. You may also be able to dispense with it where documents use a default declared using

, but that risks propagating an incorrect declaration. A xml2EncDefaultProxyHTMLCharsetOut

can remove that risk, but is likely to be a bigger processing overhead than enabling ProxyHTMLMeta.

declarations and convert them to real HTTP headers, in keeping with the original purpose of this form of the HTML element.

This directive will cause modproxyhtml to strip HTML comments. Note that this will also kill off any scripts or styles embedded in comments (a bogosity introduced in 1995/6 with Netscape 2 for the benefit of then-older browsers, but still in use today). It may also interfere with comment-based processors such as SSI or ESI: be sure to run any of those before modproxyhtml in the filter chain if stripping comments!

The optional third argument may define any of the following Flags. Flags are case-sensitive.

Ignore HTML links (pass through unchanged)

Pass embedded script and style sections through untouched.

Last-match. If this rule matches, no more rules are applied (note that this happens automatically for HTML links).

Opposite to L. Overrides the one-change-only default behaviour with HTML links.

Use Regular Expression matching-and-replace. from-pattern

a replacement string that may be based on the regexp. Regexp memory is supported: you can use brackets () in the from-pattern

If R is not set, it will use string-literal search-and-replace. The logic is starts-with in HTML links, but contains in scripting events and embedded script and style sections.

Use POSIX extended Regular Expressions. Only applicable with R.

Match at start only. This applies only to string matching (not regexps) and is irrelevant to HTML links.

Interpolate environment variables in to-pattern

will be replaced by the value of environment variable varname

The optional fourth cond argument defines a condition that will be evaluated per Request, provided ProxyHTMLInterp

is On. If the condition evaluates FALSE the map will not be applied in this request. If TRUE, or if no condition is defined, the map is applied.

A cond is evaluated by the Expression Parser. In addition, the simpler syntax of conditions in modproxyhtml 3.x for HTTPD 2.0 and 2.2 is also supported.

Modules | Directives | FAQ | Glossary | Sitemap

Apache HTTP Server Version 2.4