Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Web API squid redirector helper client

Copyright Unmukti Technology Private Limited, India

Licensed under GNU General Public License. See LICENCE for more details.

System Requirements

Squid helper is written in Perl and is currently running on following systems:

It can run on any POSIX compliant Unix system which has:

  • Perl >= 5.14.x
    • IO::Socket
    • optionally Cache::Memcached::Fast (for memcached enabled helper)
    • Cache:Memcached on OpenWrt

Memcached Support

A local memcached server is required on Squid machine. Cache::Memcached::Fast module is required to use memcached. The helper file with memcached support is

Default time for caching the results is 60 seconds.

my $CACHE_TIME = 60;

The result for each request is cached in memcached and charcoal server is not queried unless result is not found in the cache.

To install memcached on your machine, please refer to the documentation provided by your distribution. For Debian/Ubuntu, you may follow these steps:

apt-get update

apt-get install memcached

systemctl enable memcached

systemctl restart memcached

Following is a transcript of a successful telnet session to memcached:

telnet localhost 11211
Connected to localhost.
Escape character is '^]'.
STAT pid 1108
STAT uptime 11402
STAT time 1503303182
STAT version 1.4.25 Ubuntu
STAT libevent 2.0.21-stable
STAT pointer_size 64
STAT rusage_user 0.144000
STAT rusage_system 0.176000
STAT curr_connections 5
STAT total_connections 7
Connection closed by foreign host.

Squid Versions supported

Squid-2.x is supported in compatibility mode with -c argument to the helper. While Squid-3.x and Squid-4.x are supported natively.

Setup and Configuration

Add following lines to squid.conf:

url_rewrite_program /path/to/ YOUR_API_KEY
url_rewrite_children X startup=Y idle=Z concurrency=1

Configuration as External ACL Helper:

external_acl_type charcoal_helper ttl=60 negative_ttl=60 children-max=25 children-startup=5 children-idle=2 concurrency=10 %URI %SRC %IDENT %METHOD %% %MYADDR %MYPORT /etc/config/squid-helpers/ <API_KEY>
acl charcoal external charcoal_helper
http_access deny !charcoal
#deny_info http://your-deny-domain/cgi-bin/blockmsg.cgi?url=%u&clientaddr=%i&clientuser=%a charcoal

Adjust the values of X, Y and Z for your environment. Typically, X=10, Y=2 and Z=1 works fine on ALIX and Routerboard with around 10 machines in the network.

In order to obtain API key, kindly write to

Alternatively, self-host charcoal server -

Managing the ACL rules

Head to and login with the credentials provided with the API key.


No releases published


No packages published