Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole. It effectively blocks advertisements and tracking domains for all devices connected to the network by intercepting DNS requests.

Once installed, you configure your router to use Pi-hole as the primary DNS server, and it begins filtering DNS requests according to its block lists. Pi-hole provides a web interface for monitoring and managing the DNS requests and blocked domains.

Requirements: A Raspberry Pi with Raspberry Pi OS (Raspbian) or a Debian PC / VM, root / sudo access, a static local IPv4. Recommendation: Do yourself a favor by using Ethernet, not WiFi!

PiHole Installation

  1. Download and execute the install script:

    If curl is not installed on your system, you can install it with:

    sudo apt install curl -y

    Then install Pi-hole:

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

  2. Follow the installation wizard:

    The wizard will ask you if you really have a static local IPv4, which upstream DNS servers to use, whether you want the default blocklist, if you want to install the web interface, and if you want detailed logs.

    After the web interface question, it will ask you whether you wish to install the web server and required PHP modules. Make sure to hit yes, otherwise the web interface will not work.

  3. Change the primary DNS of your router:

    Set the IP address of your Pi-hole as the primary DNS server.

  4. Access the Web Interface:

    After the installation finishes, the login password for the web interface will be displayed in the terminal. Make sure to save it somewhere safe.

    You can access the interface at http://ip.address/admin.

Local DNS Configuration

In your Pi-hole Web Interface, navigate to Local DNS → DNS Records. Here you can create DNS records for IP addresses. Make sure to use a domain suffix like .local that does not exist on the public internet to avoid conflicts. Example:

router.homelab.local → 192.168.0.1

You can now ping or use nslookup on the configured domain to verify that the query is resolved correctly.

Whitelist & Blacklist

If Pi-hole blocks queries you do not want to be blocked, you can whitelist them in the Domains section. It works the other way around too: you can manually block certain domains by blacklisting them.

You can block both root domains and specific subdomains. Pi-hole also supports wildcards, meaning it will block the root domain and all of its subdomains.

Adding Adlists

To add more adlists, navigate to Adlists and paste the link of the list you want to add. Then click Add.

After that, either run pihole -g in the Pi-hole's command line or navigate to Tools → Update Gravity to update the gravity database. This is needed to pull and apply the domains from the newly added lists.