NAME

Net::Squid::ReverseProxy - setup a HTTP reverse proxy with Squid

VERSION

Version 0.04

SYNOPSIS

    use Net::Squid::ReverseProxy;

    my $squid = Net::Squid::ReverseProxy->new(
                     'squid' => '/path/to/squid',
                     'squid_conf' => '/path/to/squid.conf',
                     'squid_version' => '3.0');

    $squid->init_reverseproxy;
    sleep 1;

    $squid->add_dstdomain_proxy('dstdomain' => 'www.example.com',
                           'original_server' => ['192.168.1.10'])
            or die "can't add dstdomain";

    $squid->add_dstdomain_proxy('dstdomain' => 'mail.example.com',
                          'original_server' => ['192.168.1.20',
                                                '192.168.1.30:8080'],
                             'load_balance' => 'round-robin')
            or die "can't add dstdomain";

    print "The dstdomain www.example.com exists? ";
    print $squid->exists_dstdomain_proxy('www.example.com') ? "yes\n" : "no\n";

    use Data::Dumper;
    print Dumper $squid->list_dstdomain_proxies;

    $squid->remove_dstdomain_proxy('www.example.com')
            or die "can't remove dstdomain";

METHODS

new()

Create an object. Please specify the full path of both squid executable program and squid config file, with the version number of squid. Currently squid-2.7, 3.0, 3.1 branches were tested.

   my $squid = Net::Squid::ReverseProxy->new(
                     'squid' => '/path/to/squid',
                     'squid_conf' => '/path/to/squid.conf',
                     'squid_version' => '3.0');

Before using this module, you must have squid installed in the system. You could get the latest source from its official website squid-cache.org, then install it following the words in INSTALL document. For example,

        % ./configure --prefix=/usr/local/squid
        % make
        # make install

init_reverseproxy()

Warnning: the config file will be overwritten by this method, you should execute the method only once at the first time of using this module. It's used to initialize the setting for squid reverse proxy.

To keep backward compatibility, there is a method of init_squid_for_reverseproxy() which is an alias to this method.

You could pass the additional arguments like below to the method:

    $squid->init_reverseproxy(
      'cache_mem' => 200,
      'maximum_object_size' => 4096,
      'maximum_object_size_in_memory' => 64,
      'cache_dir_size' => 1024,
      'visible_hostname' => 'squid.domain.com',
      'cache_dir' => '/data/squidcache',
    );

cache_mem: how large memory (MB) squid will use for cache, default 50

maximum_object_size: the maximum object size (KB) squid will cache with, default 2048

maximum_object_size_in_memory: the maximum object size (KB) squid will cache with in memory, default 64

cache_dir_size: how large disk (MB) squid will use for cache, default 50

visible_hostname: visiable hostname, default localhost.localdomain

cache_dir: path to cache dir, default /tmp/squidcache

After calling this method, you MUST sleep at least one second to wait for squid to finish starting up before any further operation.

If initialized correctly, it will make squid run and listen on TCP port 80 for HTTP requests. If initialized failed, you may check /tmp/cache.log for details.

add_dstdomain_proxy()

Add a rule of reverseproxy based on dstdomain (destination domain). For example, you want to reverse-proxy the domain www.example.com, whose backend webserver is 192.168.1.10, then do:

    $squid->add_dstdomain_proxy('dstdomain' => 'www.example.com',
                          'original_server' => ['192.168.1.10']);

Here 'dstdomain' means destination domain, 'original_server' means backend webserver. If you have two backend webservers, one is 192.168.1.20, whose http port is 80 (the default), another is 192.168.1.30, whose http port is 8080, then do:

    $squid->add_dstdomain_proxy('dstdomain' => 'www.example.com',
                          'original_server' => ['192.168.1.20',
                                                '192.168.1.30:8080'],
                             'load_balance' => 'round-robin');

Here 'load_balance' specifies an algorithm for balancing http requests among webservers. The most common used algorithms are round-robin and sourcehash. The latter is used for session persistence mostly. See squid.conf's document for details. If you want all traffic go to the first webserver, and only when the first webserver gets down, the traffic go to the second webserver, then don't specify a load_balance algorithm here.

exists_dstdomain_proxy()

Whether a reverseproxy rule for the specified destination domain exists.

    $squid->exists_dstdomain_proxy('www.example.com');

Returns 1 for exists, 0 for non-exists.

list_dstdomain_proxies()

List all reverseproxy rules in the config file. It returns a data structure of a reference to AoA, so you will dump it with Data::Dumper.

    use Data::Dumper;
    print Dumper $squid->list_dstdomain_proxies;

remove_dstdomain_proxy()

Remove reverseproxy rule(s) for the specified destination domain.

    $squid->remove_dstdomain_proxy('www.example.com');

AUTHOR

Jeff Pang <pangj@arcor.de>

BUGS/LIMITATIONS

If you have found bugs, please send email to <pangj@arcor.de>, I will appreciate it much.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::Squid::ReverseProxy

For the general knowledge of installing and setup squid, please reference documents and wiki on squid-cache.org, or subscribe to squid user's mailing list, or, you can email me in private. For Chinese you could download and read the Chinese version of "Squid: The Definitive Guide" translated by me:

    http://squidcn.spaces.live.com/blog/cns!B49104BB65206A10!229.entry

COPYRIGHT & LICENSE

Copyright 2009 Jeff Pang, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Net::Squid::ReverseProxy

perl -MCPAN -e shell
install Net::Squid::ReverseProxy