Apache::FilteringProxy - A configurable rewriting proxy module for HTTP servers in mod_perl.

Add the following to an Apache VirtualHost config:

    <VirtualHost ...>
        # domain with a wildcard subdomain alias (ooo...tricky)
        ServerName *.resources.somedomain.com

        ServerAdmin root@localhost.localdomain

        # some document root...empty or whatever you want to be seen if
        # mod_perl gets disabled or something similar
        DocumentRoot /var/www/html

        SetHandler  perl-script
        PerlHandler Apache::FilteringProxy
        PerlSetVar FilteringProxyMode normal
        PerlSetVar FilteringProxyConfig /some/absolute/path/to/config.xml

        ErrorLog /var/log/httpd/resources.somedomain.com-error_log
        CustomLog /var/log/httpd/resources.somedomain.com-access_log \
                  combined
    </VirtualHost>

Modify resources in the configuration file specified in FilteringProxyConfig.

    # make slashdot.org available via myslashdot.resources.somedomain.com
    <resource id="myslash" name="MySlash" url="http://www.slashdot.org">
        <host-include>slashdot.org</host-include>
        <domain-include>someotherdomain.com</domain-include>
    </resource>

Three modes are offered with this module (normal, admin, and mirror).

The Apache::FilteringProxy module provides a rewriting proxy for HTTP servers. This module was originally created to allow remote access of resources that are restricted to using IP-based authentication.

Perl modules: LWP::UserAgent XML::EasyOBJ DBI (for admin mode)

The ability to configure a wildcard subdomain i.e. *.subdomain.apu.edu (example use below)

Three modes are offered with this module (normal, admin, and mirror).

"normal" mode is used for a specific resource that will be limited to proxying a finite number of hosts/domains.

"admin" mode is used to configure a resource that will proxy every host/domain that it encounters by rewriting *all* HTTP URLs. The main purpose for this mode is to allow for interactive additions of new resources. It is used by the administrative tool bundled with the module.

"mirror" mode is used for a site that contains URLs you need to have rewritten into the proper proxied URLs. For instance, you have a page that contains URLs for slashdot (e.g. http://slashdot.org/) and you have configured a resource named "myslashdot" which includes the domain "slashdot.org". All instances of http://slashdot.org/blah would be rewritten to ~ http://myslashdot.resources.somedomain.com/blah. So if perchance you have multiple resources with the same host or domain specified in their configuration, then the first will be used.

Example configuration for a normal proxied site:

    <VirtualHost ...>
        # domain with a wildcard subdomain alias (ooo...tricky)
        ServerName *.resources.somedomain.com

        ServerAdmin root@localhost.localdomain

        # some document root...empty or whatever you want to be seen if
        # mod_perl gets disabled or something similar
        DocumentRoot /var/www/html

        SetHandler  perl-script
        PerlHandler Apache::FilteringProxy
        PerlSetVar FilteringProxyMode normal
        PerlSetVar FilteringProxyConfig /some/absolute/path/to/config.xml

        ErrorLog /var/log/httpd/resources.somedomain.com-error_log
        CustomLog /var/log/httpd/resources.somedomain.com-access_log \
                  combined
    </VirtualHost>

Example configuration for a mirror proxied site:

    <VirtualHost ...>
        # domain with a wildcard subdomain alias (ooo...tricky)
        ServerName *.mirror.somedomain.com
        ServerAlias mirror.somedomain.com

        ServerAdmin root@localhost.localdomain

        # some document root...empty or whatever you want to be seen if
        # mod_perl gets disabled or something similar
        DocumentRoot /var/www/html

        SetHandler  perl-script
        PerlHandler Apache::FilteringProxy
        PerlSetVar FilteringProxyMode mirror
        PerlSetVar FilteringProxyServername somedomain.com
        PerlSetVar FilteringProxyResourceDomain resources.somedomain.com
        PerlSetVar FilteringProxyConfig /some/absolute/path/to/config.xml

        ErrorLog /var/log/httpd/mirror.somedomain.com-error_log
        CustomLog /var/log/httpd/mirror.somedomain.com-access_log \
                  combined
    </VirtualHost>

Example configuration for an admin proxied site:

    <VirtualHost ...>
        # domain with a wildcard subdomain alias (ooo...tricky)
        ServerName *.admin.somedomain.com

        ServerAdmin root@localhost.localdomain

        # some document root...empty or whatever you want to be seen if
        # mod_perl gets disabled or something similar
        DocumentRoot /var/www/html

        SetHandler  perl-script
        PerlHandler Apache::FilteringProxy
        PerlSetVar FilteringProxyMode admin
        PerlSetVar FilteringProxyServername somedomain.com
        PerlSetVar FilteringProxyConfig /some/absolute/path/to/config.xml

        ErrorLog /var/log/httpd/admin.somedomain.com-error_log
        CustomLog /var/log/httpd/admin.somedomain.com-access_log \
                  combined
    </VirtualHost>

Why we use a subdomain and not URI mapping:

    Much easier to translate all absolute (http://) URLs we run into
    than it is to try and catch all root relative (/) URLs

Why we use a wildcard subdomain:

    Who wants to have a hundred vhosts for proxying and have to restart 
    apache on every change?  Both multiple vhosts and multiple ports
    get old pretty quick.

This module still does not yet implement caching abilites and may never do so. Configure it to use a real proxy if this is important to you.

http://www.w3.org/Protocols/rfc2616/rfc2616.html

http://perl.apache.org/

David Castro <dcastro@apu.edu>

Copyright (C) 2000-2002 David Castro <dcastro@apu.edu> Azusa Pacific University

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA