Awesome Open Source
Awesome Open Source

Pi-hole
Tutorial to install a Network-wide ad blocking, DNS- and DHCP server on Raspberry Pi


paypal 🍺 Please support me: Although all my software is free, it is always appreciated if you can support my efforts on Github with a contribution via Paypal - this allows me to write cool projects like this in my personal time and hopefully help you or your business.


The Pi-hole is a DNS sinkhole that protects your devices from unwanted content, without installing any client-side software.

  • Easy-to-install: our versatile installer walks you through the process, and takes less than ten minutes
  • Resolute: content is blocked in non-browser locations, such as ad-laden mobile apps and smart TVs
  • Responsive: seamlessly speeds up the feel of everyday browsing by caching DNS queries
  • Lightweight: runs smoothly with minimal hardware and software requirements
  • Robust: a command line interface that is quality assured for interoperability
  • Insightful: a beautiful responsive Web Interface dashboard to view and control your Pi-hole
  • Versatile: can optionally function as a DHCP server, ensuring all your devices are protected automatically
  • Scalable: capable of handling hundreds of millions of queries when installed on server-grade hardware
  • Modern: blocks ads over both IPv4 and IPv6
  • Free: open source software which helps ensure you are the sole person in control of your privacy

Setup the Raspberry Pi

For all my home-network projects I run Raspbian Debian Stretch Lite. The setup is trivial:

  • Get yourself a Raspberry Pi and a SD-card
  • Use Etcher to format and SD-card

Upgrade packages and distribution

sudo apt-get update && sudo apt-get upgrade
sudo apt-get dist-upgrade

Upgrade firmware

sudo raspi-config
sudo rpi-update

Install my custom MOTD

This changes the login screen. Just copy it from this repository

sudo cp ~/motd.sh /etc/profile.d/motd.sh
sudo chown root:root /etc/profile.d/motd.sh
sudo chmod +x /etc/profile.d/motd.sh
sudo rm /etc/motd

Use sudo nano /etc/ssh/sshd_config to change to PrintLastLog no

Enable root login

  • Set a root password via sudo passwd root
  • Edit sudo vi /etc/ssh/sshd_config and set PermitRootLogin yes
  • Restart SSHD /etc/init.d/ssh restart

Enable password-less login

  • Create the .ssh directory via install -d -m 700 ~/.ssh
  • Create a SSH key on your PC: ssh-keygen -t rsa -b 4096 -C "[email protected]"
  • Install your public key for user 'pi' cat ~/.ssh/id_rsa.pub | ssh [email protected] 'cat >> .ssh/authorized_keys'
  • Install your public key for user 'root' cat ~/.ssh/id_rsa.pub | ssh [email protected] 'cat >> .ssh/authorized_keys'

Cleanup & Install extra tools

sudo apt-get install -y sysstat vnstat screen
sudo apt-get purge apache2
sudo apt-get autoremove 

Enable NTP time

timedatectl set-ntp true 
timedatectl status

# Time will be in GMT/UTC, if you want to adjust, use the following:
echo "Africa/Johannesburg" | sudo tee /etc/timezone
sudo dpkg-reconfigure --frontend noninteractive tzdata
timedatectl set-timezone Africa/Johannesburg

Reboot your Pi before continuing the next step. Login as 'root' to complete the next steps.

Install Cloudflare DNS

We will use Cloudflare via Argo Tunnel as our DNS provider

cd ~
wget https://bin.equinox.io/c/VdrWdbjqyF/cloudflared-stable-linux-arm.tgz
mkdir argo-tunnel
tar -xvzf cloudflared-stable-linux-arm.tgz -C ./argo-tunnel
rm cloudflared-stable-linux-arm.tgz
cd argo-tunnel
./cloudflared --version

To manually test it, run:

sudo ./cloudflared proxy-dns --port 54 --upstream https://1.1.1.1/.well-known/dns-query --upstream https://1.0.0.1/.well-known/dns-query

Let's install it as a system service by copying the service file and then starting it via sudo systemctl restart dnsproxy.service

Install email for notifications

We will use msmtp for this and I use my Google Apps account to send out email:

apt-get install msmtp ca-certificates mailutils
rm /usr/sbin/sendmail
ln -s /usr/bin/msmtp /usr/sbin/sendmail

Adjust /etc/msmtprc and /etc/msmtprc.aliases accordingly.

Install PiHole

This is really a one-liner via curl -sSL https://install.pi-hole.net | bash

Adjust PiHole configuration files

  1. Adjust sudo nano /etc/pihole/setupVars.conf
  • The IPV4_ADDRESS to the IP of your Pi
  • Comment out PIHOLE_DNS_1 and PIHOLE_DNS_2
  • Enable DHCP_ACTIVE and DHCP settings
  • Adjust the PIHOLE_DOMAIN
  1. Copy my whitelist.txt

  2. Adjust /etc/dnsmasq.d/

  1. Adjust /etc/hosts to setup other hosts which should be resolved in your network

Install SSL via Let's Encrypt

I am using DNS-01 authentication via Cloudflare DNS with acme.sh - this allows me to automatically renew SSL certificates without exposing services to the outside. Run the below as 'root'-user:

  1. Install acme.sh curl https://get.acme.sh | sh
  2. Register with Let's Encrypt acme.sh --upgrade --auto-upgrade --accountemail "youremail"
  3. Export your Cloudflare API-key and email:
export CF_Key="YOUR-API-KEY"
export CF_Email="YOUR-CLOUDFLARE-EMAIL"
  1. Adjust your /etc/lighthttpd/external.conf (change pihole.example.com to your own domain name)

  2. Issue your certificate and adjust the domain pihole.example.com according to your own settings

acme.sh --force --issue  --dnssleep 30 --dns dns_cf -d pihole.example.com  --reloadcmd "cat /root/.acme.sh/pihole.example.com/pihole.example.com.key /root/.acme.sh/pihole.example.com/pihole.example.com.cer | tee /root/.acme.sh/pihole.example.com/pihole.example.com.combined.pem && systemctl restart lighttpd.service"

You are done - just reboot one more time and you should be able to access Pi-Hole via https://pihole.example.com

Post-install: Make your network take advantage of Pi-hole

Once you have completed the above steps, you will need to configure your router to have DHCP clients use Pi-hole as their DNS server which ensures that all devices connecting to your network will have content blocked without any further intervention.

If your router does not support setting the DNS server, you can use Pi-hole's built in DHCP server; just be sure to disable DHCP on your router first (if it has that feature available).

As a last resort, you can always manually set each device to use Pi-hole as their DNS server.


Donations are always welcome

🍺 Please support me: If the above helped you in any way, then follow me on Twitter or send me some coins:

(BTC)    36nBgsAhBBzkTvJMut851XVj47bUrdsmQx
(ETH)    0xE572b3B1187a3Ab77D72f7d6AeCd18DF26306cfC
(BAT)    0x48c65D6f768D92d4a23E4e9d25329E7De67c14d9
(LTC)    M8TNsiQWe591HTkDtLubZeftbejfPMcoUy
(Ripple) rw2ciyaNshpHe7bCHo4bRWq6pqqynnWKQg (Tag: 2478959347)
(XLM)    GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37 (Memo ID: 909493707)

Sign up to Cointracking which uses APIs to connect to all exchanges and helps you with tax. Use Binance Exchange to trade #altcoins. Join TradingView to get trend-reports. Sign up with Coinbase and instantly get $10 in BTC. I also accept old-school PayPal.

If you have no crypto, follow me at least on Twitter.


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
shell (9,857
dns (288
letsencrypt (135
cloudflare (106
pi-hole (49
dhcp (28

Find Open Source By Browsing 7,000 Topics Across 59 Categories