Squid::Guard - Redirector for the Squid web proxy
use Squid::Guard; my $sg = Squid::Guard->new(); $sg->redir("http://proxy/cgi-bin/deny.pl";); $sg->checkf(\&check); $sg->run;
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.
API call to create a new server. Does not actually start running anything until you call
Get/set the redir page. The following macros are supported:
checkffunction result (see)
If set to the special value
CHECKF, then the return value of the checkf function, if true, is used directly as the redirection url
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
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
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.
Get/set verbosity. Currently only one level of verbosity is supported
Emit debug info
Executes only a single iteration then exits (can be used when debugging)
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.
Starts handling the requests, reading them from <STDIN> one per line in the format used by Squid to talk to the url_rewrite_program
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.
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.
Adds one or more categories.
path is the directory, relative to dbdir, containing the
Creates/updates the .db files for the categories. Will search in
path for the potential presence of the
urls plaintext files. According to the value of the
forcedbupdate flag (see), will create or update the .db file from them.
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.
Checks if a request is in one category or more
Checks if a user is in a UNIX grop
Checks if a user is in a WinBind grop
Checks if a request is for an explicit IP address
Luigi Iotti, <email@example.com>
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.