The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Squid-Guard-0.25
River stage zero No dependents
1 ++
/ Squid::Guard

NAME

Squid::Guard - Redirector for the Squid web proxy

SYNOPSYS

    use Squid::Guard;

    sub check($$) {
        my ( $self, $req ) = @_;
        return 'deny' if $req->host =~ /somethingnasty.com/;
        0;
    }

    my $sg = Squid::Guard->new();

    $sg->redir("http://proxy/cgi-bin/deny.pl";);

    $sg->checkf(\&check);

    $sg->run;

DESCRIPTION

Squid::Guard is a module for creating a simple yet flexible redirector for the Squid web cache engine. This module was inspired by squidGuard, a popular squid redirector written in C, but aims to be more flexible and in some ways simpler to use. I was happy with squidGuard and used it for years. But I needed certain extra features like the ability to differentiate between users based on some external program output, group belongings etc. squidGuard did not support this, so Squid::Guard was born.

Squid::Guard->new( opt => val, ...)

API call to create a new server. Does not actually start running anything until you call ->run().

$sg->redir()

Get/set the redir page. The following macros are supported:

%u the requested url
%p the path and the optional query string of %u, but note for convenience without the leading "/"
%a the client IP address
%n the client FQDN
%i the user name, if available
%t the checkf function result (see)
%% the % sign

If set to the special value 'CHECKF', then the return value of the checkf function, if true, is used literally as the redirection url.

$sg->checkf()

Sets the check callback function, which is called upn each request received. The check function receives as arguments the current Squid::Guard object, and a Squid::Guard::Request object on which the user can perform tests. A false return value means no redirection is to be proformed. A true return value means that the request is to be redirected to what was declared with redir() (or, in the case redir() is exactly 'CHECKF', to the exact return value, which in this case should be a complete url).

See the examples included in the distribution.

$sg->concurrency()

Enables the concurrency protocol. For now, the implementation is rather poor: the ID is simply read and echoed to squid. See url_rewrite_concurrency in squid.conf

$sg->cache()

Enables caching in expensive subs which involve spawning external processes. At the moment, caching is implemented in checkinwbgroup() (which calls wbinfo 3 times) and in checkingroup() (which can be expensive in some nss configurations). An argument must be suplied, representing the time to live of cached items, in seconds. The time to live, as the whole cached objects, are shared among all the objects belonging to this class. No problem since usually only one object is in use.

$sg->verbose()

Get/set verbosity. Currently only one level of verbosity is supported

$sg->debug()

Emit debug info

$sg->oneshot()

Executes only a single iteration then exits (can be used when debugging)

$sg->handle($req)

Handles a request, returning the empty string or the redirected url. The request can be either a string in the format passed to the redirector by squid, or a Squid::Guard::Request object. This sub is usually called internally by run() to handle a request, but can be called directly too.

$sg->run()

Starts handling the requests, reading them from <STDIN> one per line in the format used by Squid to talk to the url_rewrite_program

Black/white-list support

Squid::Guard provides support for using precompiled black or white lists, in a way similar to what squidGuard does. These lists are organized in categories. Each category has its own path (a directory) where three files can reside. These files are named domains, urls and expressions. There's no need for all three to be there, and in most situations only the domains and urls files are used. These files list domains, urls and/or (regular) expressions which describe if a request belong to the category. Using the checkf sub you decide wether to allow a request unchanged, or to redirect it when it belongs to a certain category you want to look for.

Similarly to what squidGuard does, the domains and urls files have to be compiled in .db form prior to be used. This makes it possible to run huge domains and urls lists with acceptable performance. You can find precompiled lists on the net, or create your own.

Beginning with version 0.13, there is EXPERIMENTAL support for the userdomains file. This file lists domains associated with users. The request will be checked against the domains only if the request has the associated identity corresponding to the user. The file is made of lines in the format user|domain. At the moment, the file is entirely read in memory and no corresponding .db is generated/needed. The userdomain feature is EXPERIMENTAL and subject to change. Beginning with version 0.20, if the user name begins with '+', then this is taken as a UNIX group, and the domain check will be performed if the request' identity belongs to this group. If the user name begins with '!', then the name is supposed to be a Winbind group.

$sg->dbdir()

Get/set dbdir parameter, i.e. the directory where category subdirs are found. .db files generated from domains and urls files will reside here too.

$sg->addcateg( name => path, ... )

Adds one or more categories. path is the directory, relative to dbdir, containing the domains, urls, expressions and userdomains files.

$sg->mkdb( name => path, ... )

Creates/updates the .db files for the categories. Will search in path for the potential presence of the domains and urls plaintext files. According to the value of the forcedbupdate flag (see), will create or update the .db file from them.

$sg->forcedbupdate()

Controls whether mkdb should forcibly update the .db files. If set to a false value (which is the default), existing .db files are refreshed only if older than the respective plaintext file. If set to a true value, .db files are always (re)created.

$sg->checkincateg($req, $categ, ... )

Checks if a request is in one category or more

Squid ACL support

Limited support for reading in and using Squid ACLs is provided. I included this because I found that often I needed to have the same ACLs both in squid and in the redirector (for example, if you whitelist something in Squid, then likely you want it to be whitelisted in the redirector). This feature is still quite limited and EXPERIMENTAL.

$sg->readsquidcfg($file)

Reads the given squid config file (default is /etc/squid/squid.conf) looking only for acl statements, and only of some basic type.

$sg->checkinacl($req, $acl, ... )

Checks if a request is in a squid.conf acl (or more).

Currently only the following acl types are supported:

src
dstdomain
port
proto
method

Other types will be added when needed. Patches are welcome.

Other help subs that can be used in the checkf function

$sg->checkingroup($user, $group, ... )

Checks if a user is in a UNIX grop

$sg->checkinwbgroup($user, $group, ...)

Checks if a user is in a WinBind grop

$sg->checkinaddr($req)

Checks if a request is for an explicit IP address This is only a wrapper for $req-checkinaddr()>, maybe you want to use that instead.

AUTHOR

Luigi Iotti, <luigi@iotti.biz>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Luigi Iotti

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.