To be completely honest, the internet scares me. Or better, the amount of scary stuff that is on it, scares me. So now that my son is old enough to have his own PC in his bedroom, I looked around to see what was available to make sure that he doesn’t get exposed to material that is well above his age. They grow up quick enough anyway.

Now as someone who runs Ubuntu on his server, and OS X on his MacBook, I am already one step ahead of most parents, who have to deal with a Microsoft Windows environment of some sort. Good luck to you. This blog post depends on a Linux server of some sort, and although the client can be any operating system, I strongly advice you to stick to a *nix based desktop.

After dismissing most options available (things like OpenDNS, and a variety of dedicated applications to block any harmful content), I decided that however I was going to implement it, it would have to be by using a whitelist, rather than the normal practice of a blacklist. The reasoning behind this is that the amount of harmful content changes every minute, and no amount of blacklisting will catch 100% of it. With a whitelist, everything has to be vetted by me, but it ensures total control over their web experience. I also wanted to be able to approve/deny new websites as my son requests them, with little effort required on my side.

Something that sits between the client and the internet would be the perfect solution, and I quickly stumbled upon TinyProxy. As the name implies, the application is small, efficient, easy to manage and it supports blacklisting and whitelisting. Perfect.

• A server running your favourite Linux distribution. I personally use Ubuntu, but for the purpose of this guide, it doesn’t matter.
• TinyProxy as installed by your favourite package manager. For Ubuntu that’s as easy as apt-get install tinyproxy, but obviously that will be different if you run something else. Make a note of the version number of TinyProxy though, as we’ll need version 1.6.5 or later.
• A webserver running on your server. Apache2 is what I use, but as long as it supports PHP, then it doesn’t matter. What does matter though, is that the webserver should be able to access your TinyProxy whitelist file, which if you have both TinyProxy and the webserver running on the same server will be the case.
• A client configured to use TinyProxy. This can be Firefox, Internet Explorer, Chrome, Opera, or any other browser you like to use. Be aware though that as soon as your child learns what a proxy is and how to remove it from his PC/laptop, the whole plan falls apart.

Before you continue with the next section, make sure that your webserver is able to serve some pages, and that you have confirmed that TinyProxy is working correctly for you.

Installation

Grab the tinyproxy-admin.tar.gz package and unpack it somewhere on your server. There are a number of files in there, each of them I will describe below.

tinyproxy.32
tinyproxy.64 – These two binaries are the 1.6.5 binary patched with a small change to allow TinyProxy’s child processes to refresh their filter list when the parent receives a SIGHUP signal and when the whitelist file is changed. These changes have also been submitted to the development version of TinyProxy, but because apt-get on my Ubuntu system installs 1.6.5, I have used that code base. Eventually these patches will appear in the Ubuntu package manager, but until then, these will do. The extension indicates whether the binary is for 32-bit, or 64-bit *nix.

tinyproxy – This is the TinyProxy start file (usually found in /etc/init.d), which contains a couple of changed lines. The permission on the tinyproxy.log files is by default set to restrictive. It needs to be read by the webserver’s user, which means that setting it to 644 everytime we start TinyProxy is required.

The files below need to be put in your TinyProxy configuration directory, usually /etc/tinyproxy.

tinyproxy.conf – This contains only the required changes to your distribution’s version. The ErrorFile, PidFile and Filter locations need to match your installation, and to switch from blacklisting to whitelisting, the FilterDefaultDeny parameter needs to be set to Yes.

whitelist – This contains just a single line; localhost. You need to whitelist the domain that your webserver runs on, otherwise it won’t work. If your local webserver can be reached through a proper domain name, then change localhost to that instead.

403.html – This is the file referred to by the ErrorFile directive in the tinyproxy.conf file. It contains two variables which need to be changed to match your system.

The following files are part of the administration interface and will need to be put in a directory that can be served by your local webserver. For instance, if your webserver uses /var/www as the root directory, put these in a new directory called /var/www/tinyproxy. The pages should then be able to be accessible by navigating to the http://your.webserver.domain/tinyproxy url.

config.php – This is the configuration for the administration interface. Make sure that the variables match your configuration, and if you want it to notify you by Twitter each time a new domain approval request is made, enter your details in there too.

style.css
filter.html
admin.html
filter.php
img (dir) – These are the remaining files which do not require any modification.

How it all works

Whenever a client is requesting a webpage from a domain, the request is done through TinyProxy. If it finds a line in the whitelist file for the domain, it lets the request pass through, but if it doesn’t, an error 403 occurs (Forbidden) and the 403.html page is served to the client. The included 403.html file calls the filter.html file internally and passes it the website that the client is trying to access.

When the request is made, the domain gets added to the whitelist file, but with a prefix of M|, therefore still not matching a proper whitelisted domain name. And it is this mechanism which allows me to approve or deny domains whilst keeping the whitelists all in one place. The admin interface simply drops the M| prefix if the domain gets approved, or changes it to D| if it remains denied. Easy peasy :o)

• Install TinyProxy using package manager
• Install webserver
• Confirm the above are working
• Download tinyproxy-admin.tar.gz
• Amend config.php
• Move config.php, style.css, filter.html, admin.html, filter.php and the img directory to a subdirectory beneath your webserver
• Amend TinyProxy startup script: tinyproxy
• Amend TinyProxy configuration file: tinyproxy.conf
• Amend whitelist and move it to the TinyProxy configuration directory
• Amend 403.html and move it to the TinyProxy configuration directory
• Replace tinyproxy binary with patched version
• Restart TinyProxy
• Breath out ;o)

Thanks!

Update 26.7.2008

I’ve updated a bit in my script on the receiving side, so that subjects are stripped from their Fwd: (as mail forwarded from Google Mail) tag. This should make it a bit easier to send me the spam… lot’s of it, please :)

Ebay auction for FCKD.net

Seems that some MAKE users have finally found my website, and in the space of three weeks have discovered my old TiVo project (as reported on MAKE: Blog) and the digital picture frame laptop (as reported on MAKE: Blog). Won’t be long before they discover the Xbox IR mod too and break my bandwidth limit for this month :D