"Fossies" - the Fresh Open Source Software Archive

Member "Apache2-ModProxyPerlHtml-4.0/README" (11 May 2020, 11449 Bytes) of package /linux/www/apache_httpd_modules/Apache2-ModProxyPerlHtml-4.0.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 3.6_vs_4.0.

    1 NAME
    2     Apache2::ModProxyPerlHtml - rewrite HTTP headers and HTML links for
    3     reverse proxy usage
    4 
    5 DESCRIPTION
    6     Apache2::ModProxyPerlHtml is the most advanced Apache output filter to
    7     rewrite HTTP headers and HTML links for reverse proxy usage. It is
    8     written in Perl and exceeds all mod_proxy_html.c limitations without
    9     performance lost.
   10 
   11     Apache2::ModProxyPerlHtml is very simple and has far better
   12     parsing/replacement of URL than the original C code. It also supports
   13     meta tag, CSS, and javascript URL rewriting and can be used with
   14     compressed HTTP. You can now replace any code by other, like changing
   15     image names or anything else. mod_proxy_html can't do all of that. Since
   16     release 3.x ModProxyPerlHtml is also able to rewrite HTTP headers with
   17     Refresh url redirection and Referer.
   18 
   19     The replacement capability concern only the following HTTP content type:
   20 
   21             text/javascript
   22             text/html
   23             text/css
   24             text/xml
   25             application/.*javascript
   26             application/.*xml
   27 
   28     other kind of file, will be left untouched (or see ProxyHTMLContentType
   29     and ProxyHTMLExcludeContentType).
   30 
   31 AVAILIBILITY
   32     You can get the latest version of Apache2::ModProxyPerlHtml from CPAN
   33     (http://search.cpan.org/).
   34 
   35 PREREQUISITES
   36     You must have Apache2, mod_proxy, mod_perl and IO::Compress::Zlib perl
   37     modules installed on your system.
   38 
   39   Installation on RH/CentOs
   40     Install Apache2, apxs, the Epel repository (for mod_perl install) and
   41     the Perl Module IO::Compress:
   42 
   43             yum install httpd httpd-devel
   44             yum install epel-release
   45             yum install perl-IO-Compress
   46 
   47     Install ModPerl, minimal version to work with Apache 2.4 is 2.0.10:
   48 
   49             yum list | grep mod_perl
   50             yum --enablerepo=epel -y install mod_perl mod_perl-devel
   51 
   52     Enable mod_perl:
   53 
   54             a2enconf mod_perl
   55             systemctl reload apache2
   56 
   57     The Apache module mod_ssl is not available by default, install it:
   58 
   59             yum install mod_ssl
   60 
   61     If the firewall is enabled you might want to allow access to the Apache
   62     services
   63 
   64             firewall-cmd --permanent --add-service=http
   65             firewall-cmd --permanent --add-service=https
   66             firewall-cmd --reload
   67 
   68   Installation on Debian/Ubuntu
   69     To have Apache2 server and apxs command:
   70 
   71             apt install apache2 apache2-dev
   72 
   73     ModPerl can be installed using:
   74 
   75             apt install libapache2-mod-perl2 libapache2-mod-perl2-dev
   76 
   77     ModProxyPerlHtml need additional Perl module IO::Compress:
   78 
   79             apt install libio-compress-perl
   80 
   81     Enable mod_proxy:
   82 
   83             a2enmod proxy
   84             a2enmod proxy_http
   85             a2enmod proxy_ftp
   86             a2enmod proxy_connect
   87 
   88     Enable the configuration and mod_perl:
   89 
   90             a2enmod perl
   91 
   92 INSTALLATION
   93             % perl Makefile.PL
   94             % make && make install
   95 
   96 APACHE CONFIGURATION
   97     On Debian/Ubuntu set the following configuration into the VirtualHost
   98     section of files /etc/apache2/sites-available/default-ssl.conf and
   99     /etc/apache2/sites-available/000-default.conf. On CentOS/RedHat add it
  100     to /etc/httpd/conf.d/vhost.conf.
  101 
  102         ProxyRequests Off
  103         ProxyPreserveHost Off
  104         ProxyPass       /webcal/  http://webcal.domain.com/
  105 
  106         PerlInputFilterHandler Apache2::ModProxyPerlHtml
  107         PerlOutputFilterHandler Apache2::ModProxyPerlHtml
  108         SetHandler perl-script
  109         # Use line below and comment line above if you experience error:
  110         # "Attempt to serve directory". The reason is that with SetHandler
  111         # DirectoryIndex is not working 
  112         # AddHandler perl-script *
  113         PerlSetVar ProxyHTMLVerbose "On"
  114         LogLevel Info
  115 
  116 
  117         <Location /webcal/>
  118             ProxyPassReverse /
  119             PerlAddVar ProxyHTMLURLMap "/ /webcal/"
  120             PerlAddVar ProxyHTMLURLMap "http://webcal.domain.com /webcal"
  121         </Location>
  122 
  123     Note that here FilterHandlers are set globally, you can also set them in
  124     any <Location> part to set it locally and avoid calling this Apache
  125     module globally.
  126 
  127     If you want to rewrite some code on the fly, like changing images
  128     filename you can use the perl variable ProxyHTMLRewrite under the
  129     location directive as follow:
  130 
  131         <Location /webcal/>
  132             ...
  133             PerlAddVar ProxyHTMLRewrite "/logo/image1.png /images/logo1.png"
  134             # Or more complicated to handle space in the code as space is the
  135             # pattern / substitution separator character internally in ModProxyPerlHtml
  136             PerlAddVar ProxyHTMLRewrite "ajaxurl[\s\t]*=[\s\t]*'/blog' ajaxurl = '/www2.mydom.org/blog'"
  137             ...
  138         </Location>
  139 
  140     this will replace each occurence of '/logo/image1.png' by
  141     '/images/logo1.png' in the entire stream (html, javascript or css). Note
  142     that this kind of substitution is done after all other proxy related
  143     replacements.
  144 
  145     In some conditions javascript code can be replaced by error, for
  146     example:
  147 
  148             imgUp.src = '/images/' + varPath + '/' + 'up.png';
  149 
  150     will be rewritten like this:
  151 
  152             imgUp.src = '/URL/images/' + varPath + '/URL/' + 'up.png';
  153 
  154     To avoid the second replacement, write your JS code like that:
  155 
  156             imgUp.src = '/images/' + varPath + unescape('%2F') + 'up.png';
  157 
  158     ModProxyPerlHTML replacement is activated on certain HTTP Content Type.
  159     If you experienced that replacement is not activated for your file type,
  160     you can use the ProxyHTMLContentType configuration directive to
  161     redefined the HTTP Content Type that should be parsed by
  162     ModProxyPerlHTML. The default value is the following Perl regular
  163     expresssion:
  164 
  165             PerlAddVar ProxyHTMLContentType    (text\/javascript|text\/html|text\/css|text\/xml|application\/.*javascript|application\/.*xml)
  166 
  167     If you know exactly what you are doing by editing this regexp fill free
  168     to add the missing Content-Type that must be parsed by ModProxyPerlHTML.
  169     Otherwise drop me a line with the content type, I will give you the
  170     rigth expression. If you don't know about the content type, with FireFox
  171     simply type Ctrl+i on the web page.
  172 
  173     Some MS Office files may conflict with the above ProxyHTMLContentType
  174     regex like .docx or .xlsx files. The result is that there could suffer
  175     of replacement inside and the file will be corrupted. to prevent this
  176     you have the ProxyHTMLExcludeContentType configuration directive to
  177     exclude certain content-type. Here is the default value:
  178 
  179             PerlAddVar ProxyHTMLExcludeContentType  (application\/vnd\.openxml)
  180 
  181     If you have problem with other content-type, use this directive. For
  182     example, as follow:
  183 
  184             PerlAddVar ProxyHTMLExcludeContentType  (application\/vnd\.openxml|application\/vnd\..*text)
  185 
  186     this regex will prevent any MS Office XML or text document to be parsed.
  187 
  188     Some javascript libraries like JQuery are wrongly rewritten by
  189     ModProxyPerlHtml. The problem is that those javascript code include some
  190     code and regex that are detected as links and rewritten. The only way to
  191     fix that is to exclude those files from the URL rewritter by using the
  192     "ProxyHTMLExcludeUri" configuration directive. For example:
  193 
  194             PerlAddVar ProxyHTMLExcludeUri  jquery.min.js$
  195             PerlAddVar ProxyHTMLExcludeUri  ^.*\/jquery-lib\/.*$
  196 
  197     Any downloaded URI that contains the given regex will be returned asis
  198     without rewritting. You can use this directive multiple time like above
  199     to match different cases.
  200 
  201 LIVE EXAMPLE
  202     Here is the reverse proxy configuration I use to give access to Internet
  203     users to internal applications:
  204 
  205         ProxyRequests Off
  206         ProxyPreserveHost Off
  207         ProxyPass       /webmail/  http://webmail.domain.com/
  208         ProxyPass       /webcal/  http://webcal.domain.com/
  209         ProxyPass       /intranet/  http://intranet.domain.com/
  210 
  211 
  212         PerlInputFilterHandler Apache2::ModProxyPerlHtml
  213         PerlOutputFilterHandler Apache2::ModProxyPerlHtml
  214         SetHandler perl-script
  215         # Use line below iand comment line above if you experience error:
  216         # "Attempt to serve directory". The reason is that with SetHandler
  217         # DirectoryIndex is not working 
  218         # AddHandler perl-script *
  219         PerlSetVar ProxyHTMLVerbose "On"
  220         LogLevel Info
  221 
  222 
  223         # URL rewriting
  224         RewriteEngine   On
  225         #RewriteLog      "/var/log/apache/rewrite.log"
  226         #RewriteLogLevel 9
  227         # Add ending '/' if not provided
  228         RewriteCond     %{REQUEST_URI}  ^/mail$
  229         RewriteRule     ^/(.*)$ /$1/    [R]
  230         RewriteCond     %{REQUEST_URI}  ^/planet$
  231         RewriteRule     ^/(.*)$ /$1/    [R]
  232         # Add full path to the CGI to bypass the index.html redirect that may fail
  233         RewriteCond     %{REQUEST_URI}  ^/calendar/$
  234         RewriteRule     ^/(.*)/$ /$1/cgi-bin/wcal.pl    [R]
  235         RewriteCond     %{REQUEST_URI}  ^/calendar$
  236         RewriteRule     ^/(.*)$ /$1/cgi-bin/wcal.pl     [R]
  237 
  238 
  239         <Location /webmail/>
  240             ProxyPassReverse /
  241             PerlAddVar ProxyHTMLURLMap "/ /webmail/"
  242             PerlAddVar ProxyHTMLURLMap "http://webmail.domain.com /webmail"
  243             # Use this to disable compressed HTTP
  244             #RequestHeader   unset   Accept-Encoding
  245         </Location>
  246 
  247 
  248         <Location /webcal/>
  249             ProxyPassReverse /
  250             PerlAddVar ProxyHTMLURLMap "/ /webcal/"
  251             PerlAddVar ProxyHTMLURLMap "http://webcal.domain.com /webcal"
  252         </Location>
  253 
  254 
  255         <Location /intranet/>
  256             ProxyPassReverse /
  257             PerlAddVar ProxyHTMLURLMap "/ /intranet/"
  258             PerlAddVar ProxyHTMLURLMap "http://intranet.domain.com /intranet"
  259             # Rewrite links that give access to the two previous location 
  260             PerlAddVar ProxyHTMLURLMap "/intranet/webmail /webmail"
  261             PerlAddVar ProxyHTMLURLMap "/intranet/webcal /webcal"
  262         </Location>
  263 
  264     This gives access two a webmail and webcal application hosted internally
  265     to all authentified users through their own Internet acces. There's also
  266     one acces to an Intranet portal that have links to the webcal and
  267     webmail application. Those links must be rewritten twice to works.
  268 
  269 ROT13 obfuscation
  270     Some links can be obfucated to be hidden from google or other robots. To
  271     enable encode/decode of those links you can use the ProxyHTMLRot13Links
  272     directive as follow:
  273 
  274             PerlAddVar ProxyHTMLRot13Links All
  275 
  276     All links in the page will be decoded before being rewritten and
  277     re-encoded.
  278 
  279     If obfuscation occurs on some attributs only you can set the value as a
  280     pair of element:attribut where the decoding/encoding must be applied.
  281     For example:
  282 
  283             PerlAddVar ProxyHTMLRot13Links a:data-href
  284             PerlAddVar ProxyHTMLRot13Links a:href
  285 
  286 BUGS
  287     Apache2::ModProxyPerlHtml is still under development and is pretty
  288     stable. Please send me email to submit bug reports or feature requests.
  289 
  290 COPYRIGHT
  291     Copyright (c) 2005-2020 - Gilles Darold
  292 
  293     All rights reserved. This program is free software; you may redistribute
  294     it and/or modify it under the same terms as Perl itself.
  295 
  296 AUTHOR
  297     Apache2::ModProxyPerlHtml was created by :
  298 
  299             Gilles Darold
  300             <gilles at darold dot net>
  301 
  302     and is currently maintain by me.
  303