NAME
Squid::Guard - Redirector for the Squid web proxy
SYNOPSYS
use Squid::Guard;
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
checkffunction result (see) - %% the % sign
If set to the special value CHECKF, then the return value of the checkf function, if true, is used directly 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().
$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->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. You can decide, in the checkf function, to allow or to redirect a request belonging to a certain category. 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.
$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 a category
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
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.