Linux Web Content Filter (E2Guardian)
on Raspberry Pi and Linksys WRT54GL

E2Guardian is a very powerful web content filtering system, capable of filtering a simple home network to a complex corporate network. There are many benefits of running a web content filter, mainly for security reasons (to block users from accessing malicious sites), but other reasons as well. Perhaps you wish to block other sites that are not malicious, but are known to collect data or spy on users. For more information on what E2Guardin, please visit the website http://e2guardian.org.

This article will show how to install E2Guardian on a Raspberry Pi running the Raspian OS, and tie it to a Linksys WRT54GL router. I chose theWRT54GL router not only because the cost is around $20 to buy a decent working unit, but because it will run the popular DD-WRT firmware, which is very feature-rich compared to the limited default firmware from Linksys. The DD-WRT firmware offers the ability to point the router to a web proxy such as E2Guardian to handle all of your web filtering for traffic going through the WRT54GL router.

The E2Guardian configuration provided in this document will set it up to block all Internet traffic by default. Then, to add two access groups to allow Basic (restrictive) filtering, and Advanced (less restrictive) filtering.

Notes:

• At the time of this writing, E2Guardian does not have a frontend GUI configuration tool like its predecessor (Dansguardian). Therefore, it requres a lot of setup from the command line and editing many text files.
• I found that a Raspberry Pi 4 (with 4 GB of memory) is a nice fit to keep up with E2Guardian's CPU requirements, especially if you plan to use the MITM (man-in-the-middle) SSL content scanning.

Build the Raspberry Pi box for E2Guardian

Our first order of business is to build the box that will run E2Guardian.

1. Image Raspbian on the SD Card.
   Download Raspbian image from www.raspberrypi.org
   Write the .img file to the SD Card with the command:
   dd bs=4M if=2020-02-13-raspbian-buster-lite.img of=/dev/mmcblk0 status=progress conv=fsync
2. Boot the Raspberri Pi and wait while the root partition is resized for the entire SD Card size.
3. Log in (default un/pw = pi/raspberry)
4. Set up default settings with command:
   sudo raspi-config
   1. Change User Password : (set to your password of choice)
   2. Network options / Hostname: (your preferred hostname of your Raspberry Pi)
   3. Localisation Options / Change Timezone: (your timezone)
   4. Interfacing Options / SSH : Enable (this allows for using ssh to the Raspberry Pi for much easier configuration later)
   5. Configure static IP address:
      1. Edit the configuration file with command: sudo nano /etc/dhcpdc.conf
      2. Comment out lines so that they look like this:
         interface eth0
         static ip_address=192.168.1.250/24 (set this to your preferred IP address on your network and netmask)
         static routers=192.168.1.1
         static domain_name_servers=192.168.1.1 192.168.1.254 (set this to your local or Internet DNS servers)
   6. Configure NTP:
      1. Edit the configuration file with the command: sudo nano /etc/systemd/timesyncd.conf
      2. Comment out the lines so they look like this:
         FallbackNTP=192.168.1.1 (set to your local NTP or Internet NTP server)
      3. Check NTP configuration with the command: sudo timedatectl status
      4. Note the line “NTP service” should be “active”
   7. Disable onboard wifi and bluetooth adapters
      1. Edit the configuration file with command: sudo nano /boot/config.txt
      2. Add these lines to the end of the file

         dtoverlay=pi3-disable-wifi
         dtoverlay=pi3-disable-bt

      3. Run this command to disable the services:
         sudo systemctl disable hciuart
      4. Prepare E2Guardian log directory to use RAM instead of local disk (save on SD card wear)
         1. Add this line to /etc/fstab:
            tmpfs /var/log/e2guardian tmpfs defaults,noatime,nosuid,uid=e2guardian,gid=e2guardian,mode=0755,size=100m 0 0
      5. Install E2Guardian (note, the examples below set up an E2Guardian installation that blocks all Internet access by default, and allows for two groups: Basic, and Advanced
         1. Sync repo data with the command: sudo apt-get update
         2. Install E2Guardian with the command: sudo apt-get install e2guardian
         3. Apply fix for Debian Buster (current as of this writing). Only do this if the E2Guardian service will not start (when using the command: systemctl start e2guardian)
            1. Edit the file /lib/systemd/system/e2guardian.service, with the command:
               sudo nano /lib/systemd/system/e2guardian.service
            2. Add this line to the [Service] section:
               LimitSTACK=infinity
            3. Refresh systemd with command: sudo systemctl daemon-reload
            4. Start the e2guardian service with the command: sudo systemctl start e2guardian
            5. Check the status of the service with the command: sudo systemctl status e2guardian
            6. Should show as running now
         4. Configure the Linksys WRT54GL router (with DD-WRT)
            1. Note: the Linksys router must have the DD-WRT firmware loaded on it. See the DD-WRT website for more details: https://dd-wrt.com
            2. Note: The E2Guardian server must be on the same network as the clients. This requirements allows E2Guardian to see the source IP address of clients that are accessing the Internet through your router
            3. Add an iptables line to redirect port 80 and 443 to 8080 and 8443 on the E2Guardian server (these are the ports that will be pointed to, from the Linksys router):
               1. Edit the file /etc/rc.local with the command: sudo nano /etc/rc.local
               2. Add the lines just below “# By default this script does nothing.” like this:
                  # Enable source IP from wifi router for proxy requests
                  iptables -A PREROUTING -t nat -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8080
                  iptables -A PREROUTING -t nat -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 8443
               3. Log in to the Linksys router
               4. Navigate to Administration / Commands
               5. Place the following lines of code in the text box and click Save Firewall (note: for the IP of 192.168.1.250, fill in the IP address of your Raspberry Pi running E2Guardian):

                  #!/bin/sh
                  PROXY_IP=192.168.1.250
                  iptables -t mangle -A PREROUTING -p tcp -m multiport --dports 80,443 -s $PROXY_IP -j ACCEPT
                  iptables -t mangle -A PREROUTING -p tcp -m multiport --dports 80,443 -j MARK --set-mark 3
                  ip rule add fwmark 3 table 2
                  ip route add default via $PROXY_IP dev br0 table 2

               6. Optional: If you wanted to filter for all destination traffic, except for a certain network outside of your router (in this example, 10.1.1.0/24), you can use these lines instead of the lines above. This would only be useful if you have your Linksys router on a private network, and you want clients to reach that private network without being filtered.

                  #!/bin/sh
                  PROXY_IP=192.168.1.250
                  iptables -t mangle -A PREROUTING -p tcp -m multiport --dports 80,443 -s $PROXY_IP -j ACCEPT
                  iptables -t mangle -A PREROUTING -p tcp -m multiport ! -d 10.1.1.0/24 --dports 80,443 -j MARK --set-mark 3
                  ip rule add fwmark 3 table 2
                  ip route add default via $PROXY_IP dev br0 table 2

               7. Add these lines to the text section above to allow to bypass the web filtering completely-- NOT RECOMMENDED (you should handle this instead with E2Guardian configuration instead):
                  iptables -t mangle -A PREROUTING -p tcp --dport 80 -s [IPADDRESS] -j ACCEPT
            4. Tip: To check which interfaces are which (for the above commands), you can ssh to Linksys router and run command: vram show | grep wan. This is only needed for other model of routers that are not Linksys or the WRT54GL.
         5. Set up IP authentication (IP identification groups) for E2Guardian. This is where you can separate your clients in to groups, based on IP addresses for authentication or identification by E2Guardian (instead of users actually authenticating). This is commonly better for a small home use. For directory or advanced authentication, check the E2Guardian documentation for more details.
            1. Edit the file /etc/e2guardian/e2guardian.conf, and uncomment the line like below:
               authplugin = '/etc/e2guardian/authplugins/ip.conf'
            2. Edit the file /etc/e2guardian/lists/authplugins/ipgroups, and add a line like below for each group of IP addresses or access levels you have (this example sets up filter group 3 which corresponds to the configuration e2guardianf3.conf file, for less restrictive access):
               #Phones/devices to allow advanced (more open) filtering
               192.168.1.90-192.168.1.99 = filter3
            3. Set up less restrictive devices on the Linksys (allow Internet access since it is blocked by default)
               1. On the Linksys router, go to Status / LAN, and note the devices (Mac addresses) to set up for less restrictive access.
               2. Go to Services , and under DHCP Server, add one line for each device to assign a 192.168.1.9X IP address:
         6. 3rd party blacklists setup
            1. This is a very good blacklist: https://dsi.ut-capitole.fr/blacklists/index_en.php
            2. Add a rsync file called “z-e2guardian-bl” to the /etc/cron.weekly folder
            3. Add this line to the file and save it:
               rsync -avt rsync://ftp.ut-capitole.fr/blacklist /etc/e2guardian/lists/blacklists/dsi.ut-capitole.fr/
            4. 3rd party blacklists configuration
               1. Create a copy of the following files:
                  1. lists/bannedsitelist -> lists/bannedsitelist-basic
                  2. lists/bannedsslsitelist -> lists/bannedsslsitelist-basic
                  3. lists/bannedsitelist -> lists/bannedsitelist-advanced
                  4. lists/bannedsitelist -> lists/bannedsitelist-advanced
               2. Edit the files above and add include statements in each for desired additional category files that are downloaded above
         7. Apply the E2Guardian list files to user groups
            1. Create a copy of the following files:
               e2guardianf1.conf -> e2guardianf2.conf, e2guardianf3.conf
               examplef1.story -> e2guardianf1.story, e2guardianf2.story, e2guardianf3.story
               lists/bannedsitelist -> bannedsitelist-basic, bannedsitelist-advanced
               lists/bannedsslsitelist -> bannedsslsitelist-basic, bannedsslsitelist-advanced
               lists/bannedurllist -> bannedurllist-basic, bannedurllist-advanced
            2. Edit e2guardianf1.conf and force all traffic to be blocked by default
               1. Change the line to: storyboard = '/etc/e2guardian/e2guardianf1.story'
               2. Edit e2guardianf1.story and force all traffic to be blocked
               3. Uncomment the blocks of code as below:
                  # To block all access to this group
                  # uncomment next 4 lines
                  function(checkrequest)
                  if(true,,105) return setblock
                  function(sslexceptioncheck)
                  function(localsslcheckrequest)
                  # To create blanket block for http
                  # uncomment next line and one condition line.
                  #function(checkblanketblock)
                  #if(true,,502) return setblock # = ** total blanket
                  function(checkblanketblock)
                  if(true,,502) return setblock
                  #if(siteisip,,505) return setblock # = *ip ip blanket
                  # To create blanket block for SSL
                  # uncomment next line and one condition line.
                  #function(sslcheckblanketblock)
                  #if(true,,506) return setblock # = **s total blanket
                  function(sslcheckblanketblock)
                  if(true,,506) return setblock
                  #if(siteisip,,507) return setblock # = **ips ip blanket
               4. Edit e2guardianf2.conf and change “bannedsitelist”, “bannedsslsitelist”, and “bannedurllist” to the -basic versions of the files (bannedsitelist-basic, bannedsslsitelist-basic, bannedurllist-basic).
               5. Edit e2guardianf3.conf and change “bannedsitelist”, “bannedsslsitelist”, and “bannedurllist” to the -advanced versions of the files (bannedsitelist-advanced, bannedsslsitelist-advanced, bannedurllist-advanced)
               6. Enable Antivirus content scanning for browser downloads:
                  1. Note: The freshclam process will generate a lot of extra CPU load and causes the Raspberry Pi 3 to freeze while it consumes all of the CPU. May need to disable this by default.
                  2. Check that ClamAV is installed, with the command: sudo dpkg -l | grep clamav
                  3. Check that ClamAV is running, with the command: sudo systemctl status clamav
                  4. Enable the ClamAV service with the command: sudo systemctl enable clamav
                  5. Optionally, start the service if it was not running above with the command: sudo systemctl start clamav
                  6. Edit the file /etc/e2guardian/e2guardian.conf
                  7. Uncomment the line so it looks like this:
                     contentscanner = '/etc/e2guardian/contentscanners/clamdscan.conf'
                  8. To disable ClamAV (in case of CPU issues):
                     1. Run commands:
                     2. sudo systemctl stop clamav-daemon
                     3. sudo systemctl disable clamav-daemon
                     4. sudo systemctl stop clamav-freshclam
                     5. sudo systemctl disable clamav-freshclam
               7. Enable SSL content scanning (MITM or man-in-the-middle scanning). This enables E2Guardian to examine encrypted content for https websites:
                  1. Note: This will generate a lot of extra CPU load. The Raspberry Pi 3 was not able to handle this feature by default, may need more tweaking.
                  2. Create a directory: /etc/e2gaurdian/ssl . Then, in this directory follow these steps:
                  3. Generate a key for the rootCA, with the command: openssl genrsa 4096 > private_root.pem
                  4. Generate the root CA certificate: openssl req -new -x509 -days 3650 -key private_root.pem -out my_rootCA.crt
                  5. Create a DER format version of root certificate: openssl x509 -in my_rootCA.crt -outform DER -out my_rootCA.der
                  6. Generate a key for use with upstream SSL conections: openssl genrsa 4096 > private_cert.pem
                  7. Create a directory called generatedcerts to store the generated certificates. This directory must be writable by the e2guardian user
                  8. Edit the file /etc/e2guardian/e2guardian.conf, and uncomment the lines like below:
                     cacertificatepath = '/etc/e2guardian/ssl/my_rootCA.crt'
                     caprivatekeypath = '/etc/e2guardian/ssl/private_root.pem'
                     certprivatekeypath = '/etc/e2guardian/ssl/private_cert.pem'
                     generatedcertpath = '/etc/e2guardian/ssl/generatedcerts'
                     enablessl = on
                     
                  9. Edit each group file to enable SSL inspection. Example: /etc/e2guardian/e2guardianf2.conf
                     1. Comment out the line: sslmitm = on
                  10. Copy the root certificates to each device to be scanned so that MITM will work without browser certificate errors:
                      1. Copy the my_rootCA.crt and my_rootCA.der you created earlier in the process to each computer or device you wish to enable MITM filtering for.
                  11. Installation on Android devices:
                      1. Run Chrome.
                         1. Navigate to a place that you place the certificate (i.e. a web server)
                         2. Download my_rootCA.crt
                         3. Go to Settings / Security / Install from SD Card (Install certificates from SD card)
                         4. Navigate to Downloads / my_rootCA.crt
                         5. A prompt should come up to install the certificate. Check all checkboxes and tap OK.
                      2. Run Firefox
                         1. Navigate to a place that you place the certificate (i.e. a web server)
                         2. Download my_rootCA.crt
                         3. When prompted to install, tap OK.
                  12. Installation on Linux:
                      1. Open a web browser and copy the certificate from a network location (i.e. a web server, etc.)
                      2. Download my_rootCA.crt
                      3. Installation in Chrome:
                         1. Open Settings / Advanced / Certificates
                         2. Under Root Authorities, click Import
                         3. Browse to the file saved above and click OK.
                      4. Installation in Firefox:
                         1. Open Settings / Security / Certificates
                         2. Under Root Authorities, click Import
                         3. Browse to the file saves above and click OK.
                  13. Installation on Windows:
                      1. Open a web browser and copy the certificate from a network location (i.e. a web server, etc.)
                      2. Download my_rootCA.crt
                      3. Installation for Edge and Internet Explorer:
                         1. Double click on the certificate to open it.
                         2. Click Install
                         3. Select “Local Computer” and Next.
                         4. Select “Trusted Root Certificate Store” and click Next.
                         5. Click Finish.
                      4. Installation in Chrome:
                         1. Open Settings / Advanced / Certificates
                         2. Under Root Authorities, click Import
                         3. Browse to the file saved above and click OK.
                      5. Installation in Firefox:
                         1. Open Settings / Security / Certificates
                         2. Under Root Authorities, click Import

Troubleshooting

1. E2guardian seems to stop responding. Checking “sudo systemctl status e2guardian” shows “out of memory:
   1. Adjust “httpworkers” setting in /etc/e2guardian/e2guardian.conf.
   2. For a guide on how many httpworkers to set for, temporarily enable the stats with the “dstats” option. Disable it when not being used to avoid unnecessary writes to the SD card.
      time - a timestamp of when the stats were logged
      httpw - the number of children (httpworkers) running at that time or available
      busy - how many children (httpworkers) were busy serving requests or used
      free - how many were doing nothing
      wait - how many connections were waiting
      births - how many childrens were spawned
      deaths - how many were terminated
      conx - the number of connections
      conx/s - the number of connections per second
      Source: https://github.com/e2guardian/e2guardian/wiki/Performance-Tuning
2. E2Guardian stops responding, but checking /var/log/e2guardian/dstats.log, httpworkers is maxing out (at 500).
   1. If MITM is enabled, try to locate the website causing the issue (and see if it’s MS Edge as well) and whitelist it. (Credit: my post: https://github.com/e2guardian/e2guardian/issues/588).
3. E2Guardian startup errors:
   1. To find errors for the E2Guardian service, run command: e2guardian -N
4. Time-based blocking for the storyboarding is no longer working (as of this writing). It is added to v5.4 dev. https://github.com/e2guardian/e2guardian/issues/529
5. Upgrading E2Guardian past default 5.3.1 version:
   1. Download .deb package, (i.e. from : http://e2guardian.traceroot.fr/v5.4.dev/)
   2. Install with command: sudo dpkg -i /home/pi/e2raspbian_buster_v5.4.dev_20200407.deb
   3. If missing dependencies exist, fix with command: sudo apt-get install -f
   4. Additional commands:
      1. To see which package is installed: sudo apt list | grep e2guardian
      2. To view files installed with a package: sudo dpkg -L e2guardian
      3. To remove a package: sudo dkpg -r e2guardian
   5. Copy each default config from /etc/e2guardian/configs/ to /etc/e2guardian/ as needed, open, and copy over elements from the older configs. New config files are rewritten.
      1. e2guardian.conf
      

Blocking Facebook

One of the main uses I chose for E2Guardian is to completely block Facebook (facebook.com) as well as all of the Facebook tracking URLs. Many websites link to Facebook's Centra platform to track users and their activity. This information is collected without the user's consent. The steps below allow E2Guardian to completely block traffic sent to Facebook no matter which website is being visited, allowing a much safer browsing experience. Best of all, letting E2Guardian do this work takes out the extra work of configuring browsers and plugins from doing it.

To block all of Facebook and the tracking URLs for Facebook Centra, add the lines below to the /etc/e2guardian/lists/bannedsitelist file.

facebook.com
facebook.net
fbcdn.net
instagram.com
cdninstagram.com
tfbnw.net
fb.com
fbsbx.com