mod_proxy_html: Configuration

mod_proxy_html Version 2.4 (Sept-Nov 2004)

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: -ProxyHTMLURLMap from-pattern to-pattern flags

+ProxyHTMLURLMap from-pattern to-pattern [flags] [cond]

This is the key directive for rewriting HTML links. When parsing a document, whenever a link target matches from-pattern, the matching portion will be rewritten to to-pattern.

@@ -24,6 +32,13 @@ 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 +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. +using SSI directives) will not apply. This flexible configuration +is enabled by the ProxyHTMLInterp directive, or can +be disabled for speed.

Flags for ProxyHTMLURLMap

Flags are case-sensitive.

L

flags

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.

R

Use Regular Expression matching-and-replace. from-pattern is a regexp, and to-pattern a replacement string that may be @@ -61,8 +79,35 @@ 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. +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. +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 +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 +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.

ProxyHTMLDoctype

@@ -82,6 +127,10 @@ 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 +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.

ProxyHTMLFixups

@@ -100,6 +149,9 @@ 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 +internationalisation support, and is +required to support some character encodings.

ProxyHTMLExtended

Syntax ProxyHTMLExtended [On|Off]

@@ -137,10 +189,57 @@ be expanded as necessary to hold the largest script or stylesheet in a page, in increments of [nnnn] as set by this directive.

The default is 8192, and will work well for almost all pages. However, if you know you're proxying a lot of pages containing stylesheets and/or -scripts bigger than 8K, it will be more efficient to set a larger buffer +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.

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 +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. +You will need one ProxyHTMLLinks directive per element, +but it can have any number of attributes. The sample configuration +defines the HTML links for standard HTML 4 and XHTML 1.

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 +(Unicode - as used internally by libxml2) will impose an additional +processing overhead. The special token ProxyHTMLCharsetOut * +will generate output using the same encoding as the input.

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 +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).