X-Git-Url: https://granicus.if.org/sourcecode?a=blobdiff_plain;f=docs%2Fmanual%2Fmod%2Fmod_proxy_html.html.en;h=d67e954a12c4ec19f94a114b6b48c4e7f7713191;hb=0ae5b1af6b6bf3048d2a124e84905f63d6507dea;hp=96262f0de5635790072f8f19dc075f076e0f0942;hpb=ede1b2f024c3a0ee845f04aa6844f5f430ac2cfa;p=apache diff --git a/docs/manual/mod/mod_proxy_html.html.en b/docs/manual/mod/mod_proxy_html.html.en index 96262f0de5..d67e954a12 100644 --- a/docs/manual/mod/mod_proxy_html.html.en +++ b/docs/manual/mod/mod_proxy_html.html.en @@ -1,23 +1,28 @@ -
-Apache HTTP Server Version 2.3
-Apache HTTP Server Version 2.5
+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.
+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. 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.
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.
mod_proxy_html was originally developed at WebÞing, whose extensive documentation may be useful to users.
@@ -50,11 +67,13 @@ extensive documentationIn order to parse non-HTML content (stylesheets and scripts), mod_proxy_html +
In order to parse non-HTML content (stylesheets and scripts) embedded +in HTML documents, mod_proxy_html has to read the entire script or stylesheet into a buffer. This buffer will be expanded as necessary to hold the largest script or stylesheet in a page, -in increments of [nnnn] as set by this directive.
+in increments of bytes 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 +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. @@ -104,7 +124,10 @@ will generate output using the same encoding as the input.
Description: | Sets an HTML or XHTML document type declaration. |
---|---|
Syntax: | ProxyHTMLDocType HTML|XHTML [Legacy] |
Default: | ProxyHTMLDocType auto (2.5/trunk versions); no FPI (2.4.x) |
Context: | server config, virtual host, directory |
Status: | Base |
Module: | mod_proxy_html |
Description: | Turns the proxy_html filter on or off. |
Syntax: | ProxyHTMLEnable On|Off |
Default: | ProxyHTMLEnable Off |
Context: | server config, virtual host, directory |
Status: | Base |
Module: | mod_proxy_html |
Specifies one or more attributes to treat as scripting events and
-apply ProxyHTMLURLMap
s to where appropriate.
+apply ProxyHTMLURLMap
s to where enabled.
You can specify any number of attributes in one or more
ProxyHTMLEvents
directives.
The default configuration defines the events in standard HTML 4 -and XHTML 1.
+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.
ProxyHTMLExtended On|Off
ProxyHTMLExtended Off
Set to Off
, HTML links are rewritten according
+
Set to Off
, HTML links are rewritten according to the
ProxyHTMLURLMap
directives, but links appearing
in Javascript and CSS are ignored.
Set to On
, all scripting events and embedded scripts or
+
Set to On
, all scripting events (as determined by
+ProxyHTMLEvents
) and embedded scripts or
stylesheets are also processed by the ProxyHTMLURLMap
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.
+
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.
+Only use them if you know you have a broken backend server. @@ -218,6 +253,7 @@ Only use them if you know you have a broken backend server.ProxyHTMLURLMap
rules.ProxyHTMLInterp On|Off
ProxyHTMLInterp Off
Specifies elements that have URL attributes that should be rewritten
using standard ProxyHTMLURLMap
s. You will need one
ProxyHTMLLinks directive per element, but it can have any number of attributes.
The default configuration defines the HTML links for standard HTML 4 -and XHTML 1.
+Normally you'll set this globally. If you set ProxyHTMLLinks 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 HTML links for standard HTML 4 and XHTML 1.
-Description: | Enables extra verbose logging for debug |
---|---|
Syntax: | ProxyHTMLLogVerbose On|Off |
Description: | Turns on or off extra pre-parsing of metadata in HTML
+<head> sections. |
Syntax: | ProxyHTMLMeta On|Off |
Default: | ProxyHTMLMeta Off |
Context: | server config, virtual host, directory |
Status: | Base |
Module: | mod_proxy_html |
Compatibility: | Version 2.4 and later; available as a third-party -for earlier 2.x versions |
If On, mod_proxy_html will log extra diagnostic information (at
-LogLevel
Info)
-including charset detection and processing and
-ProxyHTMLURLMap
matches and rewrites.
-This may be helpful in debugging a configuration.
This turns on or off pre-parsing of metadata in HTML
+ <head>
sections.
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
+<meta http-equiv="Content-Type" content="text/html;charset=foo">+
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 xml2EncDefault
, but that risks propagating an
+ incorrect declaration. A ProxyHTMLCharsetOut
+ can remove that risk, but is likely to be a bigger processing
+ overhead than enabling ProxyHTMLMeta.
The other effect of enabling ProxyHTMLMeta is to parse all
+ <meta http-equiv=...>
declarations and convert
+ them to real HTTP headers, in keeping with the original purpose
+ of this form of the HTML <meta> element.
Description: | Determines whether to strip HTML comments. |
---|---|
Syntax: | ProxyHTMLStripComments On|Off |
Default: | ProxyHTMLStripComments Off |
Context: | server config, virtual host, directory |
Status: | Base |
Module: | mod_proxy_html |