mod_proxy_html: Configuration

mod_proxy_html Version 2.4 (Sept 2004) and upwards. -Updates in Version 3 (Dec. 2006) are highlighted.

mod_proxy_html Version 3.1 (April 2009).

Configuration Directives

The following can be used anywhere in an httpd.conf or included configuration file.

ProxyHTMLEnable

Syntax: ProxyHTMLEnable On|Off

Enables mod_proxy_html filtering in a scope (<Location> +or top level/virtualhost). This also configures mod_xml2enc if present, and replaces use of +any generic filter configuration (e.g. SetOutputFilter +or FilterProvider) to configure both these modules.

ProxyHTMLURLMap

Syntax: @@ -25,7 +32,7 @@ portion will be rewritten to to-pattern.

and substitutions, including regular expression search and replace, controlled by the optional third flags argument.

Starting at version 3.0, this also supports environment variable +Starting at version 3.0, this also supports environment variable interpolation using the V and v flags, and rules may apply conditionally based on an environment variable. Note that interpolation takes place before the parse starts, so variables set during the parse (e.g. @@ -44,9 +51,9 @@ be disabled for speed.

L

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

l

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

l

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

R

Use Regular Expression matching-and-replace. from-pattern is a regexp, and to-pattern a replacement string that may be @@ -72,33 +79,33 @@ versions 1.x. Logic is starts-with in HTML links, but

$

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

V

Interpolate environment variables in to-pattern. +

V

Interpolate environment variables in to-pattern. A string of the form ${varname|default} will be replaced by the value of environment variable varname. If that is unset, it is replaced by default. The |default is optional.

NOTE: interpolation will only be enabled if ProxyHTMLInterp is On.

v

Interpolate environment variables in from-pattern. +

v

Interpolate environment variables in from-pattern. Patterns supported are as above.

NOTE: interpolation will only be enabled if ProxyHTMLInterp is On.

Conditions for ProxyHTMLURLMap

The optional cond argument specifies a condition to +

Conditions for ProxyHTMLURLMap

The optional cond argument specifies a condition to test before the parse. If a condition is unsatisfied, the URLMap will be ignored in this parse.

The condition takes the form [!]var[=val], and is +

The condition takes the form [!]var[=val], and is satisfied if the value of environment variable var is val. If the optional =val is omitted, then any value of var satisfies the condition, provided only it is set to something. If the first character is !, the condition is reversed.

NOTE: conditions will only be applied if ProxyHTMLInterp is On.

ProxyHTMLInterp

Syntax: ProxyHTMLInterp On|Off

Enables new (per-request) features of ProxyHTMLURLMap.

@@ -120,7 +127,7 @@ argument determines whether SGML/HTML or XML/XHTML syntax will be used.

Starting at version 2.0, 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.

From version 3, if the first form is used, mod_proxy_html +

From version 3, if the first form is used, mod_proxy_html 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 LogLevel Debug.

@@ -142,7 +149,7 @@ Only use them if you know you have a broken backend server.

Syntax ProxyHTMLMeta [On|Off]

Parses <meta http-equiv ...> elements to real HTTP headers.

In version 3, this is also tied in with the improved +

In version 3, this is also tied in with the improved internationalisation support, and is required to support some character encodings.

@@ -187,8 +194,8 @@ 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.

ProxyHTMLEvents

Syntax ProxyHTMLEvents attr [attr ...]

Specifies one or more attributes to treat as scripting events and apply URLMaps to where appropriate. You can specify any number of @@ -196,8 +203,8 @@ attributes in one or more ProxyHTMLEvents directives. The sample configuration defines the events in standard HTML 4 and XHTML 1.

ProxyHTMLLinks

Syntax ProxyHTMLLinks elt attr [attr ...]

Specifies elements that have URL attributes that should be rewritten using standard URLMaps as in versions 1 and 2 of mod_proxy_html. @@ -206,28 +213,8 @@ but it can have any number of attributes. The sample configuration defines the HTML links for standard HTML 4 and XHTML 1.

ProxyHTMLCharsetAlias

Syntax ProxyHTMLCharsetAlias charset alias [alias ...]

This server-wide directive aliases one or more charset to another -charset. This enables encodings not recognised by libxml2 to be handled -internally by libxml2's charset support using the translation table for -a recognised charset.

For example, Latin 1 (ISO-8859-1) is supported by libxml2. -Microsoft's Windows-1252 is almost identical and can be supported -by aliasing it:
-ProxyHTMLCharsetAlias ISO-8859-1 Windows-1252

ProxyHTMLCharsetDefault

Syntax ProxyHTMLCharsetDefault name

This defines the default encoding to assume when absolutely no charset -information is available from the backend server. The default value for -this is ISO-8859-1, as specified in HTTP/1.0 and assumed in -earlier mod_proxy_html versions.

ProxyHTMLCharsetOut

Syntax ProxyHTMLCharsetOut name

This selects an encoding for mod_proxy_html output. It should not normally be used, as any change from the default UTF-8 @@ -235,20 +222,24 @@ normally be used, as any change from the default UTF-8 processing overhead. The special token ProxyHTMLCharsetOut * will generate output using the same encoding as the input.

ProxyHTMLStartParse

Syntax ProxyHTMLStartParse element [elt*]

Specify that the HTML parser should start at the first instance -of any of the elements specified. This can be used where a broken -backend inserts leading junk that messes up the parser (example here).

ProxyHTMLCharsetAlias

ProxyHTMLCharsetDefault

ProxyHTMLStartParse

These directives from Version 3.0 are replaced by +mod_xml2enc.

Other Configuration

Normally, mod_proxy_html will refuse to run when not +

Normally, mod_proxy_html will refuse to run when not in a proxy or when the contents are not HTML. This can be overridden (at your own risk) by setting the environment variable PROXY_HTML_FORCE (e.g. with the SetEnv directive).