Squid & Squidguard -- Setup =========================== 1. Patch Pi up to current, install squid & squidguard: sudo apt-get update -y sudo apt-get update -y sudo apt-get install -y squid squidguard 2. Edit /etc/squid/squid.conf to allow access from your local network. Pick/update one of these: # Example rule allowing access from your local networks. # Adapt to list your (internal) IP networks from where browsing # should be allowed acl localnet src 10.0.0.0/8 # RFC1918 possible internal network acl localnet src 172.16.0.0/12 # RFC1918 possible internal network acl localnet src 192.168.0.0/16 # RFC1918 possible internal network Many routers' default network is 192.168.x.y. The one's used for this demo is 192.168.0.0/24: acl localnet src 192.168.0.0/24 That needs to be allowed here: # Example rule allowing access from your local networks. # Adapt localnet in the ACL section to list your (internal) IP networks # from where browsing should be allowed #http_access allow localnet http_access allow localhost Uncomment the localnet entry: # Example rule allowing access from your local networks. # Adapt localnet in the ACL section to list your (internal) IP networks # from where browsing should be allowed http_access allow localnet http_access allow localhost If necessary, increase cache size: # TAG: cache_dir # Usage: # # cache_dir Type Directory-Name Fs-specific-data [options] # [...] #Default: # cache_dir ufs /var/spool/squid 100 16 256 The default is 100MB in 16 directories with 256 subdirectories each. Given modern disk sizes, that could be upped to 1000 256 256. When changing this, invoke: /usr/sbin/squid -z to create additional swap directories, then /usr/sbin/squid -k reconfigure to tell the running squid instance about the configuration file change. To test, tweak your browser's settings to use ip-address of your Pi, port 3128 as a proxy. 3. Configure squidGuard: Files of interest: SquidGuard's log at /var/log/squidguard/squidGuard.log, the database is located underneath /var/lib/squidguard/db, Squidguard's configuration is found in /etc/squidguard/squidGuard.conf. Start out with a simple configuration file: # # CONFIG FILE FOR SQUIDGUARD # dbhome /var/lib/squidguard/db logdir /var/log/squidguard/squidGuard.log dest denied { domainlist denied/domains urllist denied/urls } acl { default { pass !denied all redirect http://localhost/block.html } } This configuration expects two text files, domains and urls, with one domain or one URL per line, named domains and urls, both underneath /var/lib/squidguard/db. A few URLs to retrieve some are: http://squidguard.mesd.k12.or.us/blacklists.tgz http://www.shallalist.de/Downloads/shallalist.tar.gz ftp://ftp.ut-capitole.fr/pub/reseau/cache/squidguard_contrib/blacklists.tar.gz Review (take your time, good luck with that), combine as needed into domains and urls expected by squidGuard, then invoke sudo /usr/bin/squidGuard -C all to organize their contents into two Berkeley DB files, domains.db and urls.db, both in /var/lib/squidguard/db/denied. Neither one must be zero-length. Depending on size of source, this can take quite some time. 4. Squid's and squidGuard's files & directories underneath need to be owned by the same user and group squid is run under. On a Pi that's proxy:proxy. Fix that: sudo chown -R proxy /var/libs/squidguard /var/log/squid* sudo chgrp -R proxy /var/libs/squidguard /var/log/squid* 5. Configure squid to use squidGuard. Up to this point squid is unaware of squidGuard. To change that, add a url_rewrite_program to /etc/squid/squid.conf, specifying rewrite program and configuration options: # OPTIONS FOR URL REWRITING # ----------------------------------------------------------------------------- # TAG: storeurl_rewrite_program # Specify the location of the executable for the Store URL rewriter. # The Store URL rewriter allows URLs to be "normalised" ; mapping # multiple URLs to a single URL representation for cache operations. # [...] #Default: # none url_rewrite_program /usr/bin/squidGuard -c /etc/squidguard/squidGuard.conf Run /usr/sbin/squid -k reconfigure 6. Test the configuration. Tweak your browser's configuration to go through the Pi's squid proxy, then go to www.facebook.com. This should fail. 7. Add a white list to the mix. Modify squidGuard.conf: # # CONFIG FILE FOR SQUIDGUARD # dbhome /var/lib/squidguard/db logdir /var/log/squidguard dest allowed { domainlist allowed/domains urllist allowed/urls } dest denied { domainlist denied/domains urllist denied/urls } acl { default { pass allowed !denied all redirect http://192.168.0.35/block.html } } Invoke sudo /usr/bin/squidGuard -C all to update the configuration (be patient). ============================================================================= Suggested test procedure (doesn't work for me, despite the filter doing a great job: echo "http://www.example.com 10.0.0.1/ - - GET" | \ squidGuard -c /etc/squidguard/squidGuard.conf -d The first entry is the URL to look up in the database. The second value (10.0.0.1) is the client's IP address, should your configuration contain IP-based blocking. The third value (the first '-') may be substituted by a user name, for user-name blocking. If the redirector is properly configured, the redirection URL is echoed back. ============================================================================= 8. Install Pi-Hole. Installing pi-hole is straightforward. Run this: curl -sSL https://install.pi-hole.net | sudo bash preferably on a Pi with little important things on it, as you are running a script downloaded straight from the net as root. It's going to ask for an outside-facing network interface (wlan0 and eth0 are viable candidates, usb0 not so much), as well as confirmation for IP address, netmask and/or default router. Pay attention to the very last screen: Make it so. +---------------------¦ Installation Complete! +---------------------+ ¦ ¦ ¦ Configure your devices to use the Pi-hole as their DNS server ¦ ¦ using: ¦ ¦ ¦ ¦ IPv4: 192.168.0.35 ¦ ¦ IPv6: Not Configured ¦ ¦ ¦ ¦ If you set a new IP address, you should restart the Pi. ¦ ¦ ¦ ¦ The install log is in /etc/pihole. ¦ ¦ ¦ ¦ View the web interface at http://pi.hole/admin or ¦ ¦ http://192.168.0.35/admin ¦ ¦ ¦ ¦ Your Admin Webpage login password is ******** ¦ ¦ ¦ ¦ ¦ ¦ ¦ +--------------------------------------------------------------------+ Hold on to that password. You'll need it to control pi-hole.