Pi-hole is a widely used DNS sinkhole with the intention of protecting your network devices from unwanted content without the need for a client-side application. Pi-hole comes with a beautiful responsive web interface dashboard from where you can view and control your Pi-hole. This software application can blocks ads over both IPv4 and IPv6 and allows you to be the sole person in control of your web privacy.
In this short article we will cover the steps that are required to install and run Pi-hole Ads Blocker on Debian Linux machine. My machine is a Debian 12 server install as seen in the following output.
jkmutai@pi02:~$ cat /etc/os-release
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm
ID=debian
HOME_URL="https://www.debian.org/"
SUPPORT_URL="https://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"Update package index on the system.
sudo apt updateInstall git command line tool
sudo apt install git vim bash-completionInstall Pi-hole Ads Blocker on Debian
Clone Pi-hole project repository from Github.
$ git clone https://github.com/pi-hole/pi-hole.git
Cloning into 'pi-hole'...
remote: Enumerating objects: 23064, done.
remote: Counting objects: 100% (23064/23064), done.
remote: Compressing objects: 100% (8365/8365), done.
remote: Total 23064 (delta 14897), reused 22635 (delta 14587), pack-reused 0
Receiving objects: 100% (23064/23064), 7.48 MiB | 365.00 KiB/s, done.
Resolving deltas: 100% (14897/14897), done.Switch to pi-hole directory.
cd "pi-hole/automated install/"Begin the installation of Pi-hole using the script created by the developers of this powerful software solution.
sudo bash basic-install.shYour installation output should look similar to the output shown below.
[✓] Root user check
.;;,.
.ccccc:,.
:cccclll:. ..,,
:ccccclll. ;ooodc
'ccll:;ll .oooodc
.;cll.;;looo:.
.. ','.
.',,,,,,'.
.',,,,,,,,,,.
.',,,,,,,,,,,,....
....''',,,,,,,'.......
......... .... .........
.......... ..........
.......... ..........
......... .... .........
........,,,,,,,'......
....',,,,,,,,,,,,.
.',,,,,,,,,'.
.',,,,,,'.
..'''.
[i] SELinux not detected
[✓] Update local cache of available packages
[✓] Checking apt-get for upgraded packages... up to date!
[i] Checking for / installing Required dependencies for OS Check...
[✓] Checking for grep
[i] Checking for dnsutils (will be installed)
[i] Waiting for package manager to finish (up to 30 seconds)
[i] Processing apt-get install(s) for: dnsutils, please wait...
----------------------------------------------------------------------
Selecting previously unselected package dnsutils.
(Reading database ... 36659 files and directories currently installed.)
Preparing to unpack .../dnsutils_1%3a9.18.19-1~deb12u1_all.deb ...
Unpacking dnsutils (1:9.18.19-1~deb12u1) ...
Setting up dnsutils (1:9.18.19-1~deb12u1) ...
----------------------------------------------------------------------
[✓] Supported OS detected
[i] Checking for / installing Required dependencies for this install script...
[✓] Checking for git
[✓] Checking for iproute2
[i] Checking for dialog (will be installed)
[✓] Checking for ca-certificates
[i] Waiting for package manager to finish (up to 30 seconds)
[i] Processing apt-get install(s) for: dialog, please wait...
----------------------------------------------------------------------
Selecting previously unselected package dialog.
(Reading database ... 36663 files and directories currently installed.)
Preparing to unpack .../dialog_1.3-20230209-1_amd64.deb ...
Unpacking dialog (1.3-20230209-1) ...
Setting up dialog (1.3-20230209-1) ...
Processing triggers for man-db (2.11.2-2) ...
----------------------------------------------------------------------Next you will get the dialog menus. In the first one you are warned that the device will be transformed into a network-wide ad blocker.
Press <Enter> to proceed with Pi-hole installation.
Your server should have a static IP address for it to function properly.
There are multiple options for Upstream DNS provider. You can also set your router as DNS server and forward requests from Pi-hole to it for more local control.
For my case the upstream DNS server is my router for full traffic control. This is powered by OPNsense.
Confirm DNS upstream server entries and accept the instalallation.
Pi-hole uses third party DNS mapping lists to block ads. Agee to include the default blocklists in the installation. This is StevenBlack’s list available in Github.
Agree to install Admin web interface unless you want to perform Pi-hole administration for command line interface.
Accept installation of lighttpd web server to serve PHP files used by Pi-hole. This gives a full functionality of Pi-hole web console.
Enable query logging that helps in troubleshooting DNS issues.
Select operational privacy mode for FTL.
Installation and configuration of Pi-hole will begin shortly after proving customization options.
----------------------------------------------------------------------
[i] IPv4 address: 192.168.1.253/24
[i] Unable to find IPv6 ULA/GUA address
[i] IPv6 address:
[i] Using upstream DNS: Custom (192.168.1.1, 192.168.1.1)
[i] Installing StevenBlack's Unified Hosts List
[i] Installing Admin Web Interface
[i] Installing lighttpd
[i] Query Logging on.
[i] Using privacy level: 0
[✗] Check for existing repository in /etc/.pihole
[i] Clone https://github.com/pi-hole/pi-hole.git into /etc/.pihole...HEAD is now at 19bfa08 Pi-hole core v5.17.3 (#5520)
[✓] Clone https://github.com/pi-hole/pi-hole.git into /etc/.pihole
[✗] Check for existing repository in /var/www/html/admin
[i] Clone https://github.com/pi-hole/web.git into /var/www/html/admin...HEAD is now at be05b0f v5.21 (#2860)
[✓] Clone https://github.com/pi-hole/web.git into /var/www/html/admin
[i] Checking for / installing Required dependencies for Pi-hole software...
[✓] Checking for cron
[i] Checking for curl (will be installed)
[✓] Checking for iputils-ping
[i] Checking for psmisc (will be installed)
[✓] Checking for sudo
[i] Checking for unzip (will be installed)
[i] Checking for idn2 (will be installed)
[✓] Checking for libcap2-bin
[i] Checking for dns-root-data (will be installed)
[✓] Checking for libcap2
[i] Checking for netcat-openbsd (will be installed)
[✓] Checking for procps
[i] Checking for jq (will be installed)
[i] Checking for lighttpd (will be installed)
[i] Checking for php-common (will be installed)
[i] Checking for php-cgi (will be installed)
[i] Checking for php-sqlite3 (will be installed)
[i] Checking for php-xml (will be installed)
[i] Checking for php-intl (will be installed)
[i] Checking for php-json (will be installed)
[i] Waiting for package manager to finish (up to 30 seconds)
[i] Processing apt-get install(s) for: curl psmisc unzip idn2 dns-root-data netcat-openbsd jq lighttpd php-common php-cgi php-sqlite3 php-xml php-intl php-json, please wait...
----------------------------------------------------------------------
Selecting previously unselected package lighttpd.
...Wait for a few seconds for the installation of Pi-hole to complete.
----------------------------------------------------------------------
[✓] Enabling lighttpd service to start on reboot...
[✗] Checking for group 'pihole'
[✓] Creating group 'pihole'
[✓] Creating user 'pihole'
[i] FTL Checks...
[✓] Detected x86_64 processor
[i] Checking for existing FTL binary...
[✓] Downloading and Installing FTL
[✓] Installing scripts from /etc/.pihole
[i] Installing configs from /etc/.pihole...
[✓] No dnsmasq.conf found... restoring default dnsmasq.conf...
[✓] Installed /etc/dnsmasq.d/01-pihole.conf
[✓] Installed /etc/dnsmasq.d/06-rfc6761.conf
[✓] Installing sudoer file
[✓] Installing latest Cron script
[✓] Installing latest logrotate script
[i] Backing up /etc/dnsmasq.conf to /etc/dnsmasq.conf.old
[✓] man pages installed and database updated
[i] Testing if systemd-resolved is enabled
[i] Systemd-resolved is not enabled
[✓] Restarting lighttpd service...
[✓] Enabling lighttpd service to start on reboot...
[i] Restarting services...
[✓] Enabling pihole-FTL service to start on reboot...
[✓] Restarting pihole-FTL service...
[i] Creating new gravity database
[i] Migrating content of /etc/pihole/adlists.list into new database
[✓] Deleting existing list cache
[i] Neutrino emissions detected...
[✓] Pulling blocklist source list into range
[✓] Preparing new gravity database
[✓] Creating new gravity databases
[i] Using libz compression
[i] Target: https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
[✓] Status: Retrieval successful
[✓] Parsed 154885 exact domains and 0 ABP-style domains (ignored 1 non-domain entries)
Sample of non-domain entries:
- "0.0.0.0"
[✓] Building tree
[✓] Swapping databases
[✓] The old database remains available
[i] Number of gravity domains: 154885 (154885 unique domains)
[i] Number of exact blacklisted domains: 0
[i] Number of regex blacklist filters: 0
[i] Number of exact whitelisted domains: 0
[i] Number of regex whitelist filters: 0
[✓] Flushing DNS cache
[✓] Cleaning up stray matter
[✓] Restarting DNS server
[✗] DNS service is NOT running
[i] Web Interface password: fTOK9xlr
[i] This can be changed using 'pihole -a -p'
[i] View the web interface at http://pi.hole/admin or http://192.168.1.253/admin
[i] You may now configure your devices to use the Pi-hole as their DNS server
[i] Pi-hole DNS (IPv4): 192.168.1.253
[i] If you have not done so already, the above IP should be set to static.
[i] The install log is located at: /etc/pihole/install.log
[✓] Installation complete!Access Pi-hole Web Dashboard
You can access Pi-hole web interface at View the web interface at http://Your_Server_IP/admin.
But first reset admin user password.
$ sudo pihole -a -p
Enter New Password (Blank for no password):
Confirm Password:
[✓] New password setUse the set password to access Pi-hole web dashboard.
Adding adlists to pi-hole
Pi-hole uses adlists – which are basically list of domains URL to block. Pi-hole will ingests this list of domains into its so-called Gravity database.
Here is example of lists that I have on my Github repository.
https://raw.githubusercontent.com/jmutai/pihole-blocklist/main/abuse.txt
https://raw.githubusercontent.com/jmutai/pihole-blocklist/main/crypto.txt
https://raw.githubusercontent.com/jmutai/pihole-blocklist/main/drugs.txt
https://raw.githubusercontent.com/jmutai/pihole-blocklist/main/porn.txt
https://raw.githubusercontent.com/jmutai/pihole-blocklist/main/malware.txt
https://raw.githubusercontent.com/jmutai/pihole-blocklist/main/ransomware.txt
https://raw.githubusercontent.com/jmutai/pihole-blocklist/main/redirect.txt
https://raw.githubusercontent.com/jmutai/pihole-blocklist/main/scam.txtTo import a new list e.g from Github URL, go to Admin Dashboard > Adlists. Under “Adlist group management” > “Add a new adlist“, input the adlist address and give it a description.
Paste the address and put comments, then click “Add“
Update gravity database when done under Tools > “Update Gravity” > “Update“
You should see Pi-hole downloading the lists and updating its database.
It is also possible to add domain or domain wildcard to whitelist or blacklist. Go to Domains , input domain name and choose the blacklist or whitelist option.
Increasing Maximum concurrent DNS queries
If you get the error “Maximum number of concurrent DNS queries reached (max: 150)“, then create custom configuration file.
sudo tee /etc/dnsmasq.d/02-custom-settings.conf<<EOF
dns-forward-max=3000
min-cache-ttl=300
rebind-domain-ok=
EOFThe default value is 150 but we are adjusting it to 3000. Restart Pi-hole after making the change.
sudo systemctl restart pihole-FTL.serviceThe number of max number of concurrent DNS queries should now be adjusted.
Using Pi-hole as DNS in your client devices
Now configure your end devices to use Pi-hole as their default DNS server. If you’re using DHCP server, update it’s configuration to assign Pi-hole IP address as DHCP server. See OPNsense configurations under Servers > DHCP Server section.
Using Pi-hole as DNS or DHCP Server
You can map domains to IP addresses using Pi-hole, under Local DNS > DNS Records.
Pi-hole uses Dnsmasq as DNS server if you desire to customize it.
DHCP server can be enabled under Settings > DHCP. It supports static DHCP leases configuration.
