.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ModProxyPerlHtml 3"
.TH ModProxyPerlHtml 3 "2012-08-15" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Apache2::ModProxyPerlHtml is the most advanced Apache output filter to rewrite
\&\s-1HTTP\s0 headers and \s-1HTML\s0 links for reverse proxy usage. It is written in Perl and
exceeds all mod_proxy_html.c limitations without performance lost.
.PP
Apache2::ModProxyPerlHtml is very simple and has far better parsing/replacement
of \s-1URL\s0 than the original C code. It also support meta tag, \s-1CSS\s0, and javascript
\&\s-1URL\s0 rewriting and can be use with compressed \s-1HTTP\s0. You can now replace any code
by other, like changing images name or anything else. mod_proxy_html can't do
all of that. Since release 3.0 ModProxyPerlHtml is also able to rewrite \s-1HTTP\s0
headers with refresh url redirection.
.PP
The replacement capability concern only the following \s-1HTTP\s0 content type:
.PP
.Vb 6
\& text/javascript
\& text/html
\& text/css
\& text/xml
\& application/.*javascript
\& application/.*xml
.Ve
.PP
other kind of file, will be left untouched (or see ProxyHTMLContentType and ProxyHTMLExcludeContentType).
.SH "AVAIBILITY"
.IX Header "AVAIBILITY"
You can get the latest version of Apache2::ModProxyPerlHtml from \s-1CPAN\s0
(http://search.cpan.org/).
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
You must have Apache2, mod_perl2 and IO::Compress::Zlib perl modules installed
on your system.
.PP
You also need to install the mod_proxy Apache modules. See documentation at
http://httpd.apache.org/docs/2.0/mod/mod_proxy.html
.SH "INSTALLATION"
.IX Header "INSTALLATION"
.Vb 2
\& % perl Makefile.PL
\& % make && make install
.Ve
.SH "APACHE CONFIGURATION"
.IX Header "APACHE CONFIGURATION"
In your Apache configuration file you have to load the following \s-1DSO\s0 modules:
.PP
.Vb 8
\& LoadModule deflate_module modules/mod_deflate.so
\& LoadModule headers_module modules/mod_headers.so
\& LoadModule proxy_module modules/mod_proxy.so
\& LoadModule proxy_connect_module modules/mod_proxy_connect.so
\& LoadModule proxy_ftp_module modules/mod_proxy_ftp.so
\& LoadModule proxy_http_module modules/mod_proxy_http.so
\& LoadModule ssl_module modules/mod_ssl.so
\& LoadModule perl_module modules/mod_perl.so
.Ve
.PP
Then in your Apache site or virtualhost configuration file use ModProxyPerlHtml*
as follow:
.PP
.Vb 3
\& ProxyRequests Off
\& ProxyPreserveHost Off
\& ProxyPass /webcal/ http://webcal.domain.com/
\&
\& PerlInputFilterHandler Apache2::ModProxyPerlHtml
\& PerlOutputFilterHandler Apache2::ModProxyPerlHtml
\& SetHandler perl\-script
\& PerlSetVar ProxyHTMLVerbose "On"
\& LogLevel Info
\&
\&
\&
\& ProxyPassReverse /
\& PerlAddVar ProxyHTMLURLMap "/ /webcal/"
\& PerlAddVar ProxyHTMLURLMap "http://webcal.domain.com /webcal"
\&
.Ve
.PP
Note that here FilterHandlers are set globally, you can also set them in any
part to set it locally and avoid calling this Apache module globally.
.PP
If you want to rewrite some code on the fly, like changing images filename you
can use the perl variable ProxyHTMLRewrite under the location directive as
follow:
.PP
.Vb 8
\&
\& ...
\& PerlAddVar ProxyHTMLRewrite "/logo/image1.png /images/logo1.png"
\& # Or more complicated to handle space in the code as space is the
\& # pattern / substitution separator character internally in ModProxyPerlHtml
\& PerlAddVar ProxyHTMLRewrite "ajaxurl[\es\et]*=[\es\et]*\*(Aq/blog\*(Aq ajaxurl = \*(Aq/www2.mydom.org/blog\*(Aq"
\& ...
\&
.Ve
.PP
this will replace each occurence of '/logo/image1.png' by '/images/logo1.png' in
the entire stream (html, javascript or css). Note that this kind of substitution
is done after all other proxy related replacements.
.PP
In some conditions javascript code can be replaced by error, for example:
.PP
.Vb 1
\& imgUp.src = \*(Aq/images/\*(Aq + varPath + \*(Aq/\*(Aq + \*(Aqup.png\*(Aq;
.Ve
.PP
will be rewritten like this:
.PP
.Vb 1
\& imgUp.src = \*(Aq/URL/images/\*(Aq + varPath + \*(Aq/URL/\*(Aq + \*(Aqup.png\*(Aq;
.Ve
.PP
To avoid the second replacement, write your \s-1JS\s0 code like that:
.PP
.Vb 1
\& imgUp.src = \*(Aq/images/\*(Aq + varPath + unescape(\*(Aq%2F\*(Aq) + \*(Aqup.png\*(Aq;
.Ve
.PP
ModProxyPerlHTML replacement is activated on certain \s-1HTTP\s0 Content Type. If you
experienced that replacement is not activated for your file type, you can use the
ProxyHTMLContentType configuration directive to redefined the \s-1HTTP\s0 Content Type
that should be parsed by ModProxyPerlHTML. The default value is the following
Perl regular expresssion:
.PP
.Vb 1
\& ProxyHTMLContentType (text\e/javascript|text\e/html|text\e/css|text\e/xml|application\e/.*javascript|application\e/.*xml)
.Ve
.PP
If you know exactly what you are doing by editing this regexp fill free to add
the missing Content-Type that must be parsed by ModProxyPerlHTML. Otherwise drop
me a line with the content type, I will give you the rigth expression. If you don't
know about the content type, with FireFox simply type Ctrl+i on the web page.
.PP
Some \s-1MS\s0 Office files may conflict with the above ProxyHTMLContentType regex like .docx or .xlsx
files. The result is that there could suffer of replacement inside and the file will be corrupted.
to prevent this you have the ProxyHTMLExcludeContentType configuration directive to exclude certain
content-type. Here is the default value:
.PP
.Vb 1
\& ProxyHTMLExcludeContentType (application\e/vnd\e.openxml)
.Ve
.PP
If you have problem with other content-type, use this directive. For example, as follow:
.PP
.Vb 1
\& ProxyHTMLExcludeContentType (application\e/vnd\e.openxml|application\e/vnd\e..*text)
.Ve
.PP
this regex will prevent any \s-1MS\s0 Office \s-1XML\s0 or text document to be parsed.
.SH "LIVE EXAMPLE"
.IX Header "LIVE EXAMPLE"
Here is the reverse proxy configuration I use to give access to Internet users
to internal applications:
.PP
.Vb 5
\& ProxyRequests Off
\& ProxyPreserveHost Off
\& ProxyPass /webmail/ http://webmail.domain.com/
\& ProxyPass /webcal/ http://webcal.domain.com/
\& ProxyPass /intranet/ http://intranet.domain.com/
\&
\&
\& PerlInputFilterHandler Apache2::ModProxyPerlHtml
\& PerlOutputFilterHandler Apache2::ModProxyPerlHtml
\& SetHandler perl\-script
\& PerlSetVar ProxyHTMLVerbose "On"
\& LogLevel Info
\&
\&
\& # URL rewriting
\& RewriteEngine On
\& #RewriteLog "/var/log/apache/rewrite.log"
\& #RewriteLogLevel 9
\& # Add ending \*(Aq/\*(Aq if not provided
\& RewriteCond %{REQUEST_URI} ^/mail$
\& RewriteRule ^/(.*)$ /$1/ [R]
\& RewriteCond %{REQUEST_URI} ^/planet$
\& RewriteRule ^/(.*)$ /$1/ [R]
\& # Add full path to the CGI to bypass the index.html redirect that may fail
\& RewriteCond %{REQUEST_URI} ^/calendar/$
\& RewriteRule ^/(.*)/$ /$1/cgi\-bin/wcal.pl [R]
\& RewriteCond %{REQUEST_URI} ^/calendar$
\& RewriteRule ^/(.*)$ /$1/cgi\-bin/wcal.pl [R]
\&
\&
\&
\& ProxyPassReverse /
\& PerlAddVar ProxyHTMLURLMap "/ /webmail/"
\& PerlAddVar ProxyHTMLURLMap "http://webmail.domain.com /webmail"
\& # Use this to disable compressed HTTP
\& #RequestHeader unset Accept\-Encoding
\&
\&
\&
\&
\& ProxyPassReverse /
\& PerlAddVar ProxyHTMLURLMap "/ /webcal/"
\& PerlAddVar ProxyHTMLURLMap "http://webcal.domain.com /webcal"
\&
\&
\&
\&
\& ProxyPassReverse /
\& PerlAddVar ProxyHTMLURLMap "/ /intranet/"
\& PerlAddVar ProxyHTMLURLMap "http://intranet.domain.com /intranet"
\& # Rewrite links that give access to the two previous location
\& PerlAddVar ProxyHTMLURLMap "/intranet/webmail /webmail"
\& PerlAddVar ProxyHTMLURLMap "/intranet/webcal /webcal"
\&
.Ve
.PP
This gives access two a webmail and webcal application hosted internally to all
authentified users through their own Internet acces. There's also one acces to
an Intranet portal that have links to the webcal and webmail application. Those
links must be rewritten twice to works.
.SH "BUGS"
.IX Header "BUGS"
Apache2::ModProxyPerlHtml is still under development and is pretty
stable. Please send me email to submit bug reports or feature
requests.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2005\-2012 \- Gilles Darold
.PP
All rights reserved. This program is free software; you may redistribute
it and/or modify it under the same terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Apache2::ModProxyPerlHtml was created by :
.PP
.Vb 2
\& Gilles Darold
\&
.Ve
.PP
and is currently maintain by me.