Teh Artikli

Manually Installing E2guardian to pfSense

18 July 2015 | Krešimir Nesek

DansGuardian package that provides web filtering capabilities seems not to work on the latest pfSense firewall distribution. Thanks to the effort of the open source community, and specifically Marcello Coutinho, e2guardian package (a fork of DansGuardian) made it to FreeBSD repos, and Marcello created a package for pfSense. While pfSense team is working to integrate the package into the official distribution to make it available through standard package management system, many people (including myself) would like to have e2guardian running right now and install it manually. Here are the step by step instruction for the manual installation process that I used to install it to my pfSense (with help from Marcello, Phil and other folks from pfSense forums).

I used VirtualBox VM while writing this guide. Steps 1 - 3 describe the process of setting up the VM and installing the prerequisites (Squid). If you have a running pfSense box with Squid where you'd like to try this out, you can skip the first 3 steps.

Step 1) Test environment:

  • I tested this procedure using VirtualBox on OS X. Here's my setup:
  • Virtual Box (BSD / FreeBSD 64bit Machine)
  • 1GB RAM, 6GB HDD
  • 2 NICs
  • .. 1st: Connected to NAT (this will be WAN in pfSense)
  • .. 2nd: Bridged to my wireless device (this will be LAN in pfSense)
  • CD-ROM with pfSense-LiveCD-2.2.3-RELEASE-amd64.iso for installation
  • After the install I chose option 2) to assign static IP address to LAN interface, I chose IP address from my home network's range (in my case it was 192.168.5.249/24)
  • I also disabled DHCP on LAN interface to prevent potential interference with home network's DHCP
  • I browsed to the admin UI at the assigned LAN's IP and went through the installation wizard, leaving everything as it except for DHCP which I disabled

Step 2) Install squid3 package

  • Install Squid package using the package managed in admin UI
  • Make Squid listen on LAN (so we can test it) and loopback (E2Guardian uses loopback to connect to squid by default)
  • Verify that squid works (for example by setting a browser to use it as proxy on LAN's IP and port 3128)

Step 3) Enable SSH access

  • System -> Advanced: Enable Secure Shell

Step 4) SSH into console (alternatively use VirtualBox/VM console if using VM)

  • choose option 8) to enter the shell

Step 5) Install e2guardian package using pkg

  • In the shell, type in the following:
	pkg #(choose yes to install package manager)
	pkg update
	pkg install e2guardian

Step 6) Download Marcello's pull request for pfSense e2guardian package

  • You can download pull request's file from: https://github.com/marcelloc/pfsense-packages/archive/be599ee41b2567459b1eaf55fff4ecb2ad3fa4ff.zip
  • In this walk-through I'll download the zip directly to pfSense box (zip has 6Mb, once unpacked it will be 22Mb). Alternative method would be to download the zip file on your computer, unzip it, only transfer e2guardian directory from the zip file to pfSense
  • To download the zip file to pfSense directly, we will first change directory to /root, and then download the file there. While in SSH shell, type the following:
	  cd /root
	  fetch https://github.com/marcelloc/pfsense-packages/archive/be599ee41b2567459b1eaf55fff4ecb2ad3fa4ff.zip

Step 7) Unzip the package and enter e2guardian directory

  • Type in the following (you should still be in /root directory in the SSH from the previous step)
	unzip be599ee41b2567459b1eaf55fff4ecb2ad3fa4ff.zip
	rm be599ee41b2567459b1eaf55fff4ecb2ad3fa4ff.zip #(we're deleting the archive since we don't need it anymore)
	cd pfsense-packages-be599ee41b2567459b1eaf55fff4ecb2ad3fa4ff/config/e2guardian/

Step 8) Copy the files to proper locations and adjust permissions

  • e2guardian.xml file contains the locations where to put each file from the e2guardian directory (and which permissions to use)
  • I've created a script to parse the XML and generate appropriate copy and chmod commands. Here's the result (which you need to execute in SSH):
cp e2guardian.inc /usr/local/pkg/e2guardian.inc
chmod 0755 /usr/local/pkg/e2guardian.inc

cp e2guardian.php /usr/local/www/e2guardian.php
chmod 0755 /usr/local/www/e2guardian.php

cp e2guardian_ldap.php /usr/local/www/e2guardian_ldap.php
chmod 0755 /usr/local/www/e2guardian_ldap.php

cp e2guardian_ldap.xml /usr/local/pkg/e2guardian_ldap.xml
chmod 0755 /usr/local/pkg/e2guardian_ldap.xml

cp e2guardian_limits.xml /usr/local/pkg/e2guardian_limits.xml
chmod 0755 /usr/local/pkg/e2guardian_limits.xml

cp e2guardian_ips_header.template /usr/local/pkg/e2guardian_ips_header.template
chmod 0755 /usr/local/pkg/e2guardian_ips_header.template

cp e2guardian_users_header.template /usr/local/pkg/e2guardian_users_header.template
chmod 0755 /usr/local/pkg/e2guardian_users_header.template

cp e2guardian_users_footer.template /usr/local/pkg/e2guardian_users_footer.template
chmod 0755 /usr/local/pkg/e2guardian_users_footer.template

cp e2guardian_about.php /usr/local/www/e2guardian_about.php
chmod 0755 /usr/local/www/e2guardian_about.php

cp e2guardian_config.xml /usr/local/pkg/e2guardian_config.xml
chmod 0755 /usr/local/pkg/e2guardian_config.xml

cp e2guardian_sync.xml /usr/local/pkg/e2guardian_sync.xml
chmod 0755 /usr/local/pkg/e2guardian_sync.xml

cp e2guardianfx.conf.template /usr/local/pkg/e2guardianfx.conf.template
chmod 0755 /usr/local/pkg/e2guardianfx.conf.template

cp e2guardian_url_acl.xml /usr/local/pkg/e2guardian_url_acl.xml
chmod 0755 /usr/local/pkg/e2guardian_url_acl.xml

cp e2guardian_site_acl.xml /usr/local/pkg/e2guardian_site_acl.xml
chmod 0755 /usr/local/pkg/e2guardian_site_acl.xml

cp e2guardian_search_acl.xml /usr/local/pkg/e2guardian_search_acl.xml
chmod 0755 /usr/local/pkg/e2guardian_search_acl.xml

cp e2guardian_pics_acl.xml /usr/local/pkg/e2guardian_pics_acl.xml
chmod 0755 /usr/local/pkg/e2guardian_pics_acl.xml

cp e2guardian_phrase_acl.xml /usr/local/pkg/e2guardian_phrase_acl.xml
chmod 0755 /usr/local/pkg/e2guardian_phrase_acl.xml

cp e2guardian_log.xml /usr/local/pkg/e2guardian_log.xml
chmod 0755 /usr/local/pkg/e2guardian_log.xml

cp e2guardian_header_acl.xml /usr/local/pkg/e2guardian_header_acl.xml
chmod 0755 /usr/local/pkg/e2guardian_header_acl.xml

cp e2guardian_groups.xml /usr/local/pkg/e2guardian_groups.xml
chmod 0755 /usr/local/pkg/e2guardian_groups.xml

cp e2guardian_file_acl.xml /usr/local/pkg/e2guardian_file_acl.xml
chmod 0755 /usr/local/pkg/e2guardian_file_acl.xml

cp e2guardian_content_acl.xml /usr/local/pkg/e2guardian_content_acl.xml
chmod 0755 /usr/local/pkg/e2guardian_content_acl.xml

cp e2guardian_blacklist.xml /usr/local/pkg/e2guardian_blacklist.xml
chmod 0755 /usr/local/pkg/e2guardian_blacklist.xml

cp e2guardian_antivirus_acl.xml /usr/local/pkg/e2guardian_antivirus_acl.xml
chmod 0755 /usr/local/pkg/e2guardian_antivirus_acl.xml

cp e2guardian.conf.template /usr/local/pkg/e2guardian.conf.template
chmod 0755 /usr/local/pkg/e2guardian.conf.template

cp e2guardian_rc.template /usr/local/pkg/e2guardian_rc.template
chmod 0755 /usr/local/pkg/e2guardian_rc.template

cp pkg_e2guardian.inc /usr/local/www/shortcuts/pkg_e2guardian.inc
chmod 0755 /usr/local/www/shortcuts/pkg_e2guardian.inc

cp e2guardian.xml  /usr/local/pkg/e2guardian.xml

Step 9) Modify config.xml to add e2guardian menu items to pfSense web UI menus

  • There are two ways to accomplish this. You can back up your existing config.xml file through web UI, edit the downloaded backup file in a text editor and then upload it back to pfSense (restore backup). Other way to do it is to edit it directly in pfSense using a console editor. I did it using the console editor and that's what I'll describe here.
  • Firstly, which ever method you intend to use, since we'll be editing the configuration file it's smart to back it up:
  • Diagnostics -> Back/Restore: Back Configuration: Download Configuration
  • Install nano editor (just because I'm not very familiar with vi, if you're comfortable with vi, you can use that and skip this step):
pkg install nano
  • Edit the config.xml file:
nano /cf/conf/config.xml
  • Press and hold the down arrow until you scroll down to an area which contains <menu> entries - you should locate the entries for squid proxy which should look something like this:
<menu>
	<name>Proxy server</name>
	<tooltiptext>Modify the proxy server's settings</tooltiptext>
	<section>Services</section>
	<url>/pkg_edit.php?xml=squid.xml&amp;id=0</url>
</menu>
  • Underneath those, you should add a menu entry for e2guardian. Position the cursor behind proxy server's closing </menu> tag, press enter to add new line, and copy paste the e2guardian menu xml fragment into the editor. Here's the fragment:
<menu>
	<name>E2guradian</name>
	<tooltiptext>E2guradian</tooltiptext>
	<section>Services</section>
	<configfile>e2guardian.xml</configfile>
</menu>
  • Next, similarly like you did for <menu> entries, you should locate the <service> entries. For example, <service> for Squid looks like this:
<service>
	<name>squid</name>
	<rcfile>squid.sh</rcfile>
	<executable>squid</executable>
	<description><![CDATA[Proxy server Service]]></description>
</service>
  • Again, position your editor's cursor behind squid's closing </service> tag, press enter to add a new line, and copy paste the e2guardian service xml fragment into the editor. Here's the fragment:
<service>
	<name>e2guardian</name>
	<rcfile>e2guardian.sh</rcfile>
	<executable>e2guardian</executable>
	<description><![CDATA[content filtering]]></description>
</service>
  • Press Ctrl-X (nano editor's command to save and close the file), y (to confirm) and press enter
  • You can find complete listing of <menu> and <service> part of the configuration file at the bottom of the page to check how the config file should look like after the editing has been completed.

Step 10) Reboot (and keep your fingers crossed :) )

  • We need to reboot pfSense in order to apply the changes in the config
  • Type exit in the SSH console, and choose option 5) from the console menu

Step 11) E2Guardian should now be ready for use!

  • Go to Services -> E2Guardian
  • Demon tab seems to be broken on first load, but just click on it (even though it is selected) and it will show up
  • Enable E2Guardian and make it listen on LAN interface (or just go and follow any DansGuardian guide, settings seem to be the same)
  • Configure the blacklist (for example, from http://www.shallalist.de/)
  • Configure categories in ACLs
  • Set your browser's proxy to LAN IP and port 8080
  • Verify everything works and that sites are being blocked (on the first try, it didn't work for me because Squid was not listening on loopback, so double check that)

Step 12) Clean up

  • We can delete the file we downloaded initially
  • Using SSH console, type in:
	cd /root
	rm -rf pfsense-packages-be599ee41b2567459b1eaf55fff4ecb2ad3fa4ff

That's it!

Reference: Relevant parts of config.xml file

...
	<installedpackages>
		<tab/>
		<menu/>
		<menu>
			<name>Proxy server</name>
			<tooltiptext>Modify the proxy server's settings</tooltiptext>
			<section>Services</section>
			<url>/pkg_edit.php?xml=squid.xml&amp;id=0</url>
		</menu>
		<menu>
			<name>E2guradian</name>
			<tooltiptext>E2guradian</tooltiptext>
			<section>Services</section>
			<configfile>e2guardian.xml</configfile>
		</menu>
		<menu>
			<name>Reverse Proxy</name>
			<tooltiptext>Modify the proxy reverse server's settings</tooltiptext>
			<section>Services</section>
			<url>/pkg_edit.php?xml=squid_reverse_general.xml&amp;id=0</url>
		</menu>
		<service/>
		<service>
			<name>squid</name>
			<rcfile>squid.sh</rcfile>
			<executable>squid</executable>
			<description><![CDATA[Proxy server Service]]></description>
		</service>
		<service>
			<name>e2guardian</name>
			<rcfile>e2guardian.sh</rcfile>
			<executable>e2guardian</executable>
			<description><![CDATA[content filtering]]></description>
		</service>
		<service>
			<name>clamd</name>
			<rcfile>clamav-clamd</rcfile>
			<executable>clamd</executable>
			<description><![CDATA[Clamav Antivirus]]></description>
		</service>
		<service>
			<name>c-icap</name>
			<rcfile>c-icap</rcfile>
			<executable>c-icap</executable>
			<description><![CDATA[Icap inteface for squid and clamav integration]]></description>
		</service>
...