Third party cookies may be stored when visiting this site. Please see the cookie information.

Installing KidSafe family friendly web proxy on the Raspberry Pi

This is a guide to installing the free KidSafe Internet filter software and proxy server onto the Raspberry Pi.

What is KidSafe?

Kidsafe provides a way to keep your family secure on the Internet. It restricts the sites that your children can visit to those that are considered safe, still allowing the parent to allow the child to continue when appropriate. The parent is in control of what the child does on the Internet.

How does it work?

KidSafe is a program designed to be installed on a squid proxy server that provides control over who is able to access which web sites. A proxy sits between the user's computer and the Internet and in this case only permits sites that the user is authorised to access. This is not a firewall although some firewalls do include this functionality.

KidSafe uses connects to existing free and open source software, specifically running on Linux based operating system (Raspbian) and using the squid proxy, lighttpd webserver and mysql server.

Installing kidsafe

Kidsafe can be installed on any Linux based computer. It is particularly suited to running on the Raspberry Pi which provides a low cost, energy efficient computer suitable for home use. The install of the current version involves a number of steps and needs a little familiarisation with Linux and configuring on the command line. It is currently recommended for those with experience in Linux and mysql, but a version that is easier to install and use will be made available in future.

To learn more about Linux on the Raspberry Pi see the Raspberry Pi guides.

Raspbian Linux

This is based on the GNU/Linux Debian Raspberry Pi Raspbian operating system. The raspi-config tool will run at first startup, or can be run using sudo raspi-config The main things to change are to expand the filesystem to use the full SD card and to change the memory for the GPU to a reduced amount (eg. 16MB).

Static network IP address

After installing the operating system we can give the Raspberry Pi an static IP address. By default the Raspberry Pi will request a dynamic IP address which is issued by your router as required. This however may change in future which would mean having to reconfigure all the client computers. Instead we provide it with an address that doesn't change such as
Note that this address can be used on the local network which is all we need here as the router will provide the translation for outgoing connections.

First find out what DHCP address has been allocated. This is shown at the end of the startup of the operating system, but can also be found using the ifconfig command – see the extract below


eth0      Link encap:Ethernet  HWaddr b8:27:eb:8a:71:a0

          inet addr:  Bcast:  Mask:


This is saying that the ethernet port 0 has an IP address of

You will also need to find out what address your router is, using the route command

$ route

Kernel IP routing table

Destination     Gateway         Genmask         Flags Metric Ref    Use Iface

default         UG    0      0        0 eth0     *        U     0      0        0 eth0

This shows that the router IP address (Gateway) is and all traffic is sent via that router.

At this point you will also need to check on what address range is being issued by the router. This depends upon the individual router. In my case I have a Belkin Wireless Router which can be reached by pointing a web browser to the IP address of the router

The LAN settings are shown below:

Belkin wireless router lan settings

In this case the local network has valid addresses from to The router is at address and any DHCP requests will be given entries between and (you can change the range of the DHCP addresses if required). I have used for this server.

To change to static IP address

cd /etc/network

sudo nano interfaces

replace the line "iface eth0 inet dhcp" with

iface eth0 inet static




You should also take a look at the file /etc/resolv.conf

and check it has a nameserver entry (probably pointing at your default gateway)

Alternatively you could point directly at your ISPs DNS servers instead.

Whilst you can dynamically reload the network interface I suggest a reboot at this stage to make sure that the configuration is correct.

sudo reboot

After logging in check using ifconfig to confirm that we have a static ip address


eth0      Link encap:Ethernet  HWaddr b8:27:eb:8a:71:a0

          inet addr:  Bcast:  Mask:


Using ssh

You can now connect to the Raspberry pi remotely (on the same network) via ssh.
If you have another linux computer on the network then from a terminal run

which will login with the same username. If you want to use a different username then prefix that before the ip address with an @ sign.
ssh pi@

If you want to connect from Windows then there are several options, but I suggest the open source software Putty.

Blocking unauthorised Internet access

As long as the proxy servers are properly configured on the clients all web traffic will go through the kidsafe filter, however it would be easy to bypass by disabling proxies on the local computer. It is therefore recommended that the router be configured to block all outgoing Internet access except that coming from the IP address of the proxy server.

This differs depending upon the particular router and so you should follow the instructions provided with the router.

Installing squid

Here we are using the Squid proxy. There are two versions available in the Debian repositories and we specifically need version 3 or later. sudo apt-get install squid3 We will configure squid later after adding the kidsafe application helper software.

Installing lighttpd

A webserver is required for handling the login and authentication. Any web server that supports php will do, but I've chosen the lightweight webserver lighttpd which uses less resources than Apache (see guide to installing lighttpd).

To install the lighttpd web server issue the command.
sudo apt-get install lighttpd

This will install and start the web server.
[ ok ] Starting web server: lighttpd.

Install mysql database

A database is required for storing the rules. I have used mysql as that is available in the repositories.

Mysql is the most popular database server, whilst there are other alternatives such as Mario DB (a fork of Mysql) or some which require less resources, most third party software for Linux is designed to use Mysql. It can be installed using

sudo apt-get install mysql-server

During the install you will be prompted for a password. Choose an appropriate password and make sure it is kept safe and not forgotten.
The password is for the mysql root user.

Install PHP

The following commands will install PHP version 5.

sudo apt-get install php5-common php5-cgi php5 php5-mysql
Note it's important to install in the order listed above. If you try to install php5 without first installing the php5-cgi package then it will install Apache as well, which we don't want for this light-weight lighttpd server.

To enable the server to handle php scripts the fastcgi-php module should be enabled by issuing in the command
sudo lighty-enable-mod fastcgi-php
Then reload the server using
sudo service lighttpd force-reload

Install phpmyadmin

Although not a requirement it is usually easier to configure mysql through the web application phpmyadmin rather than using the command line tool. I therefore suggest also installing phpmyadmin
sudo apt-get install phpmyadmin

This can be accessed by pointing a browser at the IP address with /phpmyadmin/

Set permissions on the web directory /var/www/

It is useful to change the permissions on the www directory to allow your user to update the webpages without needing to be root.

Change the directory owner and group
sudo chown www-data:www-data /var/www
allow the group to write to the directory
sudo chmod 775 /var/www
Add the pi user to the www-data group
sudo usermod -a -G www-data pi

You should logout and back in - to pick up group permissions, or if running X you can just start a new terminal.

Testing the web server

Once the setup is complete you can access the web page by pointing your browser to the proxy IP address.

You should get a page back stating that it works, but that there is no content loaded.

Installing kidsafe

Now that the pre-requisites are installed and the Raspberry Pi is at a known IP address we can install the additional code, configure the proxy server and create our initial users and rules.

Install and configuring the Squid application helper

The application helper can be downloaded below.

This includes the application helper itself (, a squid configuration file to make configuring squid easier and the basic files for the rules and sessions. The files need to be installed into the /opt directory which needs to be performed as root (sudo). Assuming the file is downloaded in the pi home directory use.

cd /opt

sudo tar -zxvf /home/pi/kidsafe-squidapp-0.2.0.tgz

The only file that needs to be configured is the file Any manual changes to the rules or sessions files will be overwritten by the application.

The include file is based on the IP address if you have a different IP address you will need to edit the file /opt/kidsafe/ and change the last line to your own IP address. You may also need to change the entry "acl local_acl dst" if you are on a different subnet.

The squid3 configuration file also needs to be updated to incorporate the squid include file.

As root (sudo) edit the file /etc/squid3/squid.conf and add the following line near the top of the configuration file before the line # TAG: dns_testnames

include /opt/kidsafe/

The files need to have the correct permissions to allow the web application to update the files. This can be done using the following commands.

cd /opt/kidsafe

sudo chown :www-data .

sudo chmod 775 .

sudo chown :proxy

sudo chmod 770

sudo chown :www-data kidsafe.rules kidsafe.session

sudo chmod 664 kidsafe.rules kidsafe.session

Squid can now be restarted using

sudo service squid3 restart

Install the web application

The web application used for logging-on and adding rules needs to be installed within the lighttpd document root directory.

Download the file below

Install this into /var/www

cd /var/www

tar -xvzf /home/pi/kidsafe-webapp-0.2.0.tgz

There is a configuration file for the web application. From a security perspective it may be a good idea to change the password for mysql. This is not mandatory as logins are only permitted from the proxy computer, but would provide additional protection if mysql was wrongly configured.

The $nolocal variable is used to allow the local computer to connect to the proxy or in the event that connections are being tunneled through an ssh tunnel on the Raspberry Pi. Chances are if you don't understand what ssh tunnels are then you don't need to change this from the default true setting.

Creating and configuring the mysql database

The code uses a mysql database for the rules and users which needs to be configured manually. This is easiest through the phpmyadmin web service (installed previously), although can be done from the command line mysql client if preferred.

First create the database kidsafe by clicking on Databases and then "Create new database".

Now create a new database user with the following settings:

  • user name: kidsafe
  • Host: Local
  • Password: <as defined in the kidsafe-config.php file> (H386Nhdheinf67190hNHUkdhtodn137bbv)

Then in Database-specific privileges enter the following

  • Database: kidsafe
  • Grant: No
  • Table-specific priveleges: No

Next click on the database on the left hand menu and use the SQL tab to execute the rules in the following file. Lines begining with # are comments and are not required, but they will help explain where default entries are being created.

Setting permissions to allow the log viewer

The log permissions need to be changed to allow the web application to view the logs. This does mean that anyone that is in the www-data group can view the logs, but this is designed to run on a dedicated computer so only adminstrators should be able to login.

cd /var/log/squid3

sudo touch kidsafe.log

sudo chown :www-data kidsafe.log

The logrotate script also needs to be updated to ensure that the logs keep the same permissions when the old logs are archived.

as root edit the file /etc/logrotate.d/squid3. After the line "test ! -e /var/run/ || /usr/sbin/squid3 -k rotate" add the following:

# Create new log for kidsafe and set ownership

touch /var/log/squid3/kidsafe.log

chown proxy:www-data /var/log/squid3/kidsafe.log

The setup is now complete. The initial setup is in the most secure setting with only adults able to access any websites. The next guide shows how to add access to appropriate websites.

Upgrading from earlier versions

If upgrading from version 0.1.x then just untar the files into the appropriate directory as listed above. There are no changes required to the database for this version.

Other Raspberry Pi Projects and tutorials

Previous Running a lightweight webserver on the Raspberry Pi (lighttpd)
Running a lightweight webserver on the Raspberry Pi (lighttpd)
Next Kidsafe filter configuration
Kidsafe filter configuration