Pi-hole

From Leo's Notes
Revision as of 02:25, 21 June 2020 by Leo (talk | contribs) (IP blocking mode info)
This page was last edited on 21 June 2020, at 02:25.

Pi-hole is a light weight application that configures a DNS and DHCP server for the purpose of blocking advertisements. It comes with an optional control panel written in PHP. As the name suggests, it is designed to run on a Raspberry Pi, although it can also be installed on anything that runs a supported version of Linux.

Running Pi-hole on the original Raspberry Pi 1 works, though the web interface might be somewhat sluggish. I am using Pi-hole as an alternative to OpenWRT with the Adblock package. One drawback with Pi-hole compared to OpenWRT is that the system needs a full blown Linux distro to function and the installation size is several orders of magnitude larger (1.7GB vs. 16MB). The initial boot time is definitely longer and the use of SQLite might cause higher wear on the SD card.

Installation

Pi-hole can be installed on a clean install of Raspbian (Raspberry Pi OS), Ubuntu, Debian, Fedora, or CentOS. The installation process can be started by running their install script with alternative methods listed on their installation page. 

# curl -sSL https://install.pi-hole.net | bash

Follow the installation steps and make a note of the admin password that is generated. If you did not see the admin password or if you've forgotten it, you can reset it with pihole -a -p.

After installation with the web interface enabled, you should be able to see the dashboard at http://pi.hole/.

Using IP Blocking Mode

An example of a Pi-hole block page

IP Blocking mode is required (over the default null blocking mode) if you wish to have a block page visible for blacklisted domains. Limitations with this mode include requiring an additional set of firewall rules to stop HTTPS connections immediately (to avoid certificate errors and slow connection timeouts) and extra overhead with connections being made to blocked hosts by your browser.

To use IP blocking mode, configure the firewall with the following rules:

# iptables -A INPUT -p tcp --dport 443 -j REJECT --reject-with tcp-reset
# iptables -A INPUT -p udp --dport 443 -j REJECT --reject-with icmp-port-unreachable
# ip6tables -A INPUT -p tcp --dport 443 -j REJECT --reject-with tcp-reset
# ip6tables -A INPUT -p udp --dport 443 -j REJECT --reject-with icmp6-port-unreachable

Then, edit /etc/pihole/pihole-FTL.conf and set BLOCKINGMODE=IP. If you are using IPv6 on your network, ensure that the IPV6_ADDRESS value in setupVars.conf is correct, otherwise connections made via IPv6 will need to timeout causing pages to take longer to load. Apply your changes by restarting pihole-FTL or with killall -SIGHUP pihole-FTL. If this works correctly, going to a blacklisted server will show a blocked page and going to the secured version of the blacklisted host will immediately result in a connection refused error.

To make these IPtable rules persistent, install the iptables-persistent package and save the rules with the following commands. 

# apt-get install iptables-persistent
# iptables-save > /etc/iptables/rules.v4
# ip6tables-save > /etc/iptables/rules.v6

Administration

TFTP / PXE Boot Support

OpenWRT TFTP Settings

Unlike in OpenWRT where you can define the TFTP settings for dnsmasq directly in Luci, with Pi-hole, you will need to define the dnsmasq DHCP options configuration in a configuration file manually.

Create a dnsmasq configuration file at /etc/dnsmasq.d/02-tftp.conf with the following lines to define the next server and next file. These are the same values that you would have entered in OpenWRT via Luci. Ensure that the TFTP root exists and contains your PXE boot files. 

# Defined within /etc/dnsmasq.d/02-tftp.conf
tftp-root=/tftpboot
dhcp-boot=pxelinux.0,10.1.2.54,10.1.2.54


Restart dnsmasq (via systemd or the Pi-hole control panel) to apply.

Updating

Updating Pi-hole is as simple as running: 

# pihole -up


Troubleshooting

Pi-hole is blocking itself when accessing pihole URL

When navigating to http://pihole/, you may see an error "Access to the following website has been denied:" and that "This is primarily due to being flagged as: Not found on any Blacklist". This is a red herring since lighttpd will serve the website blocked page for any domains it does not recognize.

You can still navigate to http://pihole/admin to view the dashboard.

See Also