This guide helps you to install Pi-hole on your Raspberry Pi 3B running Debian 12, transforming it into a network-wide ad blocker. Pi-hole filters advertisements before they reach your devices, creating a smoother browsing experience.
Pi-hole is a network-wide ad blocker that functions as a Domain Name System (DNS) sinkhole. It intercepts domain requests from devices on your network and blocks requests to known advertising, tracking, and malicious domains. Pi-hole achieves this by maintaining a blacklist of such domains and preventing them from being resolved, effectively blocking ads and tracking across all devices connected to your network.
There are several reasons why one might choose to use Pi-hole:
- Ad Blocking: Pi-hole provides comprehensive ad blocking at the network level, which means ads are blocked on all devices connected to your network, including smartphones, tablets, computers, smart TVs, and IoT devices.
- Faster Browsing: By blocking ad and tracking domains, Pi-hole can significantly reduce the amount of data loaded when browsing websites, leading to faster page loading times and a smoother browsing experience.
- Privacy Protection: Many advertising and tracking domains collect user data without consent, compromising privacy. Pi-hole helps protect privacy by blocking these domains from tracking your online activity.
- Security: Pi-hole can also block access to known malicious domains, helping to protect your devices from malware, phishing, and other online threats.
How is Pi-hole incorporated in the network?
Our network consists of Pi-hole (IP 192.168.88.10), a default gateway (Router) (IP 192.168.88.1), and a computer (PC1 192.168.88.215) (see Figure 1). These three devices are connected via a switch. The DNS server and DHCP server are running on the router. The upstream DNS servers configured on the router are both Google (8.8.8.8) and the DNS server of the ISP (Internet Service Provider).
Figure 1 - Typical LAN with Pi-Hole Blocker and Default Gateway (Router)
The DNS server is running on the Pi-hole, and it is configured to use the upstream DNS server running on the default gateway (192.168.88.1). The Pi-hole's DNS server address, 192.168.88.10, is distributed via DHCP on the default gateway to clients.
Operational Workflow
When a client 192.168.88.215 on the LAN sends a DNS request, the following steps occur:
- The client sends a DNS request to the Pi-hole server.
- Pi-hole first checks its own database of blocked and allowed domains.
- If the requested domain is found in Pi-hole's local database, Pi-hole responds directly to the client with the corresponding block or allow status.
- If the requested domain isn't found in Pi-hole's local database, it forwards the DNS request to its configured upstream DNS server, which is the default gateway.
- The default gateway, upon receiving the DNS request, checks if it contains the entry.
- If the entry is found, the default gateway resolves the domain internally and sends the response back to the Pi-hole server.
- If the entry is not found, the default gateway forwards the DNS request to its configured upstream DNS servers (likely Google in this case) to resolve the domain name into an IP address.
- The response containing the IP address for the requested domain is sent back to the Pi-hole server.
- Pi-hole caches the resolved domain entry for future use, optimizing future DNS requests.
Prerequisites:
- Raspberry Pi 3B with Debian 12 installed
- Active internet connection
- Kingston 128GB USB stick (recommended for Debian 12 installation)
1. Setting Up a Static IP Address (Optional)
While not strictly necessary, assigning a static IP address to your Raspberry Pi simplifies managing its network configuration. The steps illustrate configuring the eth0 interface. Replace the provided IP addresses, subnet mask, gateway, and DNS server details with your network's specific values.
$ ip="192.168.88.10"
$ mask="255.255.255.0"
$ br="192.168.88.255"
$ gw="192.168.88.1"
$ dns="192.168.88.1"
Delete config file for interface eth0:
$ echo "" | sudo tee /etc/network/interfaces.d/eth0
$ echo "auto eth0" | sudo tee -a /etc/network/interfaces.d/eth0
$ echo "iface eth0 inet static" | sudo tee -a /etc/network/interfaces.d/eth0
$ echo "address $ip" | sudo tee -a /etc/network/interfaces.d/eth0
$ echo "gateway $gw" | sudo tee -a /etc/network/interfaces.d/eth0
$ echo "netmask $mask" | sudo tee -a /etc/network/interfaces.d/eth0
$ echo "dns-nameservers $dns" | sudo tee -a /etc/network/interfaces.d/eth0
Restart the networking service on a Linux system:
$ sudo systemctl restart networking
2. Pi-hole Installation
Ensure your system has the latest package information by running sudo apt update:
$ sudo apt update & apt upgrade
We will use Git to clone the Pi-hole repository. Install it with sudo apt install git.
$ sudo apt install git
Clone Pi-hole repository. Navigate to your desired directory and clone the Pi-hole repository using git.
$ git clone --depth 1 https://github.com/pi-hole/pi-hole.git Pi-hole
Change directory to the install folder within the cloned repository (cd Pi-hole/automated install/) and run the installation script with sudo bash basic-install.sh. The script will guide you through the configuration process.
$ cd "Pi-hole/automated install/"
$ sudo bash basic-install.sh
3. Pi-hole Configuration
The upstream DNS server refers to the DNS server that your Pi-hole device will use to resolve domain names that are not blocked by Pi-hole's blacklist. In this case, the preferred upstream DNS server is the DNS server running on the default gateway with the IP address 192.168.88.1. Pi-hole will forward DNS queries to this server for resolution when necessary, ensuring that non-blocked domain names are resolved correctly.
Select option Custom as depicted in Figure 2.
Figure 2 - Selecting Custom DNS Server
Enter the IP addresses of both upstream DNS servers. Those are the default gateway address 192.168.88.1 and Google Public DNS server (Figure 3).
Figure 3 - Configuring Upstream DNS Server
- Choose "Yes" to include the default Pi-hole blocklist (adlist).
- Choose Yes to install Admin Web Interface
- Choose Yes to install to install the lighttpd web server and required PHP modules needed by Pi-holes.
- Choose "Yes" to log queries.
- Select the level of detail displayed in the Pi-hole web interface. Select '0' to Show everything and click Continue.
After installation, we can access the Pi-hole web interface at http://192.168.88.10/admin (replace IP with your Raspberry Pi's IP address). The default password generated during installation should be reset for security reasons (Figure 4). Use the following command in your Raspberry Pi terminal in order to change the password:
$ sudo pihole -a -p
Figure 4 - Install Screen with Generated Password
4. Customizing Pi-hole
Login to your Pi-hole Web UI with your preferred browser. By default, Pi-Hole allows only queries from devices that are at most one hop away local devices (subnet 192.168.88.0/24). Pi-hole in this setup is located within a local network and UDP port 53 is not forwarded. If we connect to Pi-hole via VPN Pi-hole queries are not allowed.
To ensure Pi-hole allows queries more than one hop away (e.g., while connecting via VPN to our home network), navigate to Settings -> DNS in the web interface and select "only on interface eth0" under "Interface settings." (Figure 5).
Figure 5 - Allow DNS Queries More than One Hop Away
5.Adding Block Lists
Block lists contain domain names known to be associated with ads. Pi-hole comes with an optional StevenBlack's blocklist out of the box. Currently, this blocklist provides 124,414 domains for blocking.
The StevenBlack's blocklist is well maintained and currently contains 124,414 domains (Figure 6). The list provides good blocking functionality without breaking normal functionality. While it may suffice for some users, many opt to add their own custom lists for enhanced blocking capabilities.
Figure 6 - Pi-hole Dashboard - 124 414 Domains on Adlist
In Pi-hole, the file named gravity.db is the database that stores all the information about domains that Pi-hole should block. It's essentially the central list used to filter out unwanted ads and trackers.
How blocking works?
- We configure Pi-hole with various ad blocklists.
- Pi-hole runs a command called pihole -g (or it might run automatically on a schedule). This command processes the adlists and extracts the domain names.
- The extracted domains are then stored in the /etc/pihole/gravity.db file.
- Whenever a device on your network tries to access the internet, Pi-hole intercepts the request and checks the domain name against /etc/pihole/the gravity.db database.
- If the domain name is found in the database, Pi-hole blocks the request, preventing ads and trackers from loading.
5.1 Adding Blocklist from Web UI
To add a new blocklist, visit https://firebog.net/ and copy multiple lists highlighted in green (see Figure 7).
Figure 7 - Firebog Block Lists
From the web Admin GUI > Adlists, paste any of the URL's above (or all at once) into the Address window, and hit Add (Figure 8).
Figure 8 - Inserting Multiple Block Lists
After you are done adding, to update gravity use either the pihole -g command from the command line, or Admin GUI > Tools > Update Gravity (Figure 9).
Figure 9 - Updating Gravity from Admin GUI
Pi-hole also automatically runs a command called 'pihole -g' on a schedule. This command processes the adlists and extracts the domain names. By default, the new gravity database is built from the blocklists at 4:03 AM, only on Sundays. This is accomplished by the following command in /etc/cron.d/pihole:
4 * * 7 root PATH="$PATH:/usr/sbin:/usr/local/bin/" pihole updateGravity >/var/log/pihole/pihole_updateGravity.log || cat /var/log/pihole/pihole_updateGravity.log
Note: The command 'pihole -g' is a shortened version of 'pihole updateGravity'."
5.2 Adding Blocklist from Command Line
We will show how to add StevenBlack's adlist using the command line interface. Firstly, we need to install sqlite3. The command refers to the command-line interface tool for interacting with SQLite databases. It allows you to manage and query SQLite databases directly from your terminal.
$ sudo apt install sqlite3
Then, execute the following command to add StevenBlack's blocklist to the gravity database:
$ sudo sqlite3 /etc/pihole/gravity.db "INSERT INTO adlist (address, enabled, comment) VALUES ('https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts', 1, 'my default adlist');"
To update gravity, use the pihole -g command from the terminal.
$ pihole -g
6. Deleting Adlists from Database
There are a few reasons why you might want to remove an adlist from gravity.db in Pi-hole:
- Unreliable or Broken Adlist:
Sometimes, an adlist might become unavailable or stop being maintained. This can lead to errors during Pi-hole's update process (pihole -g). Removing the broken list can resolve these errors and ensure a smooth update.
- Unwanted Adlist:
You might have accidentally added an adlist that you don't want to use anymore. Removing it from gravity.db will prevent those domains from being blocked by Pi-hole.
- Managing a Large Number of Adlists:
Having a very large number of adlists can slow down Pi-hole's update process. If you find you're blocking too many domains and want to streamline things, you can selectively remove some adlists to create a more focused blocking strategy.
Note: Within the Pi-hole web interface, you can disable specific adlists without removing them entirely. This prevents them from being used for blocking but keeps them in your list for future reference. However, you need to update gravity afterwards. Either use the pihole -g command from the command line or go to Admin GUI > Tools > Update Gravity.
6.1 Deleting Adlist from Database from Web UI
Individual blocklists can be removed from the database gravity.db via the Web Admin UI. Navigate to the Adlist section, select the list you want to remove, and then click on the button with the Trash icon (refer to Figure 10).
Figure 10 - Removing Default Adlist from Web Admin UI
To update gravity, you can either use the pihole -g command from the command line or go to Admin GUI > Tools > Update Gravity.
6.2 Deleting Adlist from Database from Command Line
To delete an adlist from the Pi-hole gravity database using CLI, we utilize the SQLite tool. The command follows this structure:
$ sudo sqlite3 /etc/pihole/gravity.db "DELETE FROM adlist WHERE address='https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts';"
To update gravity, use the pihole -g command from the terminal.
6.3 Deleting All Adlists from Database from Command Line
To remove all existing adlists from the Pi-hole gravity database using the command line interface (CLI), you can execute the following command:
$ sudo sqlite3 /etc/pihole/gravity.db "DELETE FROM adlist"
Rebuild gravity with pihole -g to remove the adlist contents from the gravity list.
$ pihole -g
Running pihole -g will rebuild the gravity list, incorporating the changes made by removing all adlists from the database. This process ensures that the adlist contents are removed from the gravity list, effectively stopping Pi-hole from blocking domains specified in those adlists.
7. Updating Pi-hole
The command "pihole -up" is used to update Pi-hole to the latest version available. It fetches the latest updates from the Pi-hole repositories and applies them to your Pi-hole installation (Figure 11).
$ pihole -up
Figure 11 - Updating Pi-Hole Components
8. Setting Pi-Hole DNS Server IP on Default Gateway (Router)
To ensure all devices on your network benefit from Pi-hole's ad blocking capabilities, your need to configure your router to use Pi-hole as its DNS server. This typically involves accessing your router's administration panel and locating the settings for primary and secondary DNS servers.
Set the primary DNS server address to your Raspberry Pi's IP address (where Pi-hole is installed). After saving the changes and resetting any open network connections on your devices, they will automatically utilize Pi-hole for DNS resolution, resulting in ad-free browsing.
In our case, we use a MikroTik router as the default gateway for hosts on the LAN subnet 192.168.88.0/24, with the DHCP server running on the default gateway. The DNS server IP is distributed to DHCP clients. Therefore, we need to change the DHCP settings on the MikroTik router to direct these devices to use the Pi-hole server for DNS resolution.
This can be done with a single command:
[admin@MikroTik] > ip dhcp-server/network/set 0 dns-server=192.168.88.10
Conclusion
In conclusion, this guide equips you with the knowledge and tools to set up Pi-hole on your Raspberry Pi 3B running Debian 12, transforming it into a powerful network-wide ad blocker. Pi-hole offers comprehensive ad blocking, faster browsing, enhanced privacy protection, and improved security by blocking ads, trackers, and malicious domains at the network level.
By following the step-by-step instructions provided, you can customize Pi-hole to suit your specific needs and ensure all devices on your network benefit from its ad blocking capabilities.