RPi + Pi-hole + Unbound (optional) Worksheet
THE TUTORIAL IS MEANT TO BE USED WITH THIS VIDEO!
YouTube tutorials can be a pain to actually follow, so here’s the worksheet that accompanies the video - for your convenience.
I recommend both printing this out, to use as a checklist, and keeping the page up, so you can copy-and-paste the entries.
What you need:
A Raspberry Pi 3B/3B+/4/5 (wired Ethernet recommended)
A microSD card (8GB, or larger)
A microSD reader (or SD, with an adapter)
Another computer to flash the SD card (Windows/macOS/Linux)
Admin access to your router (if you want to use the Pi-hole automatically across your entire network)
STEP 1: Flash Raspberry Pi OS to the microSD card
o Download & install Raspberry Pi Imager (from raspberrypi.com) on your computer
o In Raspberry Pi Imager:
1. Device: Select the type of Raspberry Pi you’re going to use
2. OS: Select Raspberry Pi OS (64-bit)
3. Storage: Select microSD card (assuming it’s in a reader, attached to your system)
4. Hostname: Enter a hostname, Pi-hole-1, in my case. Record your hostname here: ______________
5. Localization: Select your country’s capital city, time zone, and keyboard layout
6. User: Create a username, netserv, in my case, and a password. Record the username and password here: _____________/_____________
7. WiFi: Skip this, because you’re using wired Ethernet, right? RIGHT?
8. Remote Access: toggle Enable SSH to On, and set it to using password authentication
9. Raspberry Pi Connect: Disable
o Write (6 minutes) and verify (4 minutes). Eject the card
o Insert the card into the Pi, plug in Ethernet (preferred), then power it on (wait a minute or two to let it boot up)
o Find its IP (e.g., via your router’s client list or ping pi-hole-1 or whatever you named it in #4). Record this IP address HERE: __________________
STEP 2: Updating the Raspberry Pi
Connect to your RPi via SSH
open a terminal window on your Windows computer, WIN + R > cmd > Enter
[copy/paste >] ssh USERNAME@IP_ADDRESS_OF_RPi (for example: ssh netserv@192.168.0.11)
Enter password from step 1, #6
[copy/paste >] sudo apt update && sudo apt full-upgrade -ySTEP 3: Give the Raspberry Pi a static IP address
Reserve the Pi’s IP in your router’s DHCP, usually by creating a DHCP reservation or converting an existing DHCP lease into a reservation
or
Set a static IP address with nmcli
STEP 4: Install the latest Pi-hole
Start Pi-hole’s official installer, from SSH, with:
[copy/paste >] curl -sSL https://install.pi-hole.net | bashDuring install:
Confirm static IP warning
Select an upstream DNS provider (Quad9 (filtered, ECS, DNSSEC), if you aren’t loading Unbound)
Blocklists: Select “yes” to add StevenBlack’s Unified Hosts List
Enable logging: Select “no”
Privacy mode for FTL: Select “0 – Show Everything”
Record web interface URL here: __________________________
After install, set password, from SSH, for Pi-hole with:
[copy/paste >] sudo pihole setpassword piholeNote: you can change pihole to a different password
Record your pi-hole UI password here: ______________
Test DNS, from SSH, with:
[copy/paste >] dig @PI-HOLE_IP_ADDRESS www.google.comsudo shutdown -r nowSTOP HERE - YOU HAVE PI-HOLE RUNNING NOW!
STEP 5: Set your router to use Pi-hole
On your router (generic steps):
1. Go to LAN or DHCP settings
2. Find DNS server fields for DHCP clients
3. Set Primary DNS = your Pi-hole IP (e.g., 192.168.0.11)
4. Leave Secondary DNS blank to force clients to use Pi-hole
5. Save/apply
6. Reboot one client device or renew its DHCP lease
Confirm it’s using Pi-hole:
Visit http://Pi-hole_IP/admin > Query Log to see requests
(e.g. http://192.168.0.11/admin)
or
On a client (from console window - shows the server it used):
[copy/paste >] nslookup dad-the-engineer.com STOP HERE - YOU HAVE PI-HOLE HANDLING YOUR WHOLE NETWORK NOW!
STEP 6: Adding Unbound & configuring Pi-hole to use Unbound
Install Unbound, from SSH:
[copy/paste >] sudo apt update[copy/paste >] sudo apt install -y unboundGet the current DNS root hints:
[copy/paste >] sudo curl -o /var/lib/unbound/root.hints https://www.internic.net/domain/named.rootMinimal privacy-focused Unbound config
[copy/paste >] sudo nano /etc/unbound/unbound.conf.d/pi-hole.confcopy from here>
server:
# If no logfile is specified, syslog is used
# logfile: "/var/log/unbound/unbound.log"
verbosity: 0
interface: 127.0.0.1
port: 5335
do-ip4: yes
do-udp: yes
do-tcp: yes
# May be set to no if you don't have IPv6 connectivity
do-ip6: yes
# You want to leave this to no unless you have *native* IPv6. With 6to4 and
# Terredo tunnels your web browser should favor IPv4 for the same reasons
prefer-ip6: no
# Use this only when you downloaded the list of primary root servers!
# If you use the default dns-root-data package, unbound will find it automatically
#root-hints: "/var/lib/unbound/root.hints"
# Trust glue only if it is within the server's authority
harden-glue: yes
# Require DNSSEC data for trust-anchored zones, if such data is absent, the zone becomes BOGUS
harden-dnssec-stripped: yes
# Don't use Capitalization randomization as it known to cause DNSSEC issues sometimes
# see https://discourse.pi-hole.net/t/unbound-stubby-or-dnscrypt-proxy/9378 for further details
use-caps-for-id: no
# Reduce EDNS reassembly buffer size.
# IP fragmentation is unreliable on the Internet today, and can cause
# transmission failures when large DNS messages are sent via UDP. Even
# when fragmentation does work, it may not be secure; it is theoretically
# possible to spoof parts of a fragmented DNS message, without easy
# detection at the receiving end. Recently, there was an excellent study
# >>> Defragmenting DNS - Determining the optimal maximum UDP response size for DNS <<<
# by Axel Koolhaas, and Tjeerd Slokker (https://indico.dns-oarc.net/event/36/contributions/776/)
# in collaboration with NLnet Labs explored DNS using real world data from the
# the RIPE Atlas probes and the researchers suggested different values for
# IPv4 and IPv6 and in different scenarios. They advise that servers should
# be configured to limit DNS messages sent over UDP to a size that will not
# trigger fragmentation on typical network links. DNS servers can switch
# from UDP to TCP when a DNS response is too big to fit in this limited
# buffer size. This value has also been suggested in DNS Flag Day 2020.
edns-buffer-size: 1232
# Perform prefetching of close to expired message cache entries
# This only applies to domains that have been frequently queried
prefetch: yes
num-threads: 2
# Ensure kernel buffer is large enough to not lose messages in traffic spikes
so-rcvbuf: 1m
# Ensure privacy of local IP ranges
private-address: 192.168.0.0/16
private-address: 169.254.0.0/16
private-address: 172.16.0.0/12
private-address: 10.0.0.0/8
private-address: fd00::/8
private-address: fe80::/10
# Ensure no reverse queries to non-public IP ranges (RFC6303 4.2)
private-address: 192.0.2.0/24
private-address: 198.51.100.0/24
private-address: 203.0.113.0/24
private-address: 255.255.255.255/32
private-address: 2001:db8::/32<to here, and paste it into nano
Exit (Control-X) and Save (yes)
Enable & restart:
[copy/paste >] sudo systemctl enable unbound[copy/paste >] sudo systemctl restart unbound[copy/paste >] sudo systemctl status unbound --no-pagerTest Unbound directly on the Pi:
[copy/paste >] dig @127.0.0.1 -p 5335 cloudflare.com +dnssec +multiPoint Pi-hole to Unbound (as upstream):
Log into Pi-hole Web UI > Settings > DNS > Upstream DNS Servers:
Uncheck any public upstreams
Custom 1 (IPv4): 127.0.0.1#5335
Save
Test from a client console window:
[copy/paste >] nslookup www.dad-the-engineer.comVerify in Pi-hole Web UI:
Check Query Log to confirm queries go to 127.0.0.1
STOP HERE - YOU HAVE UNBOUND HANDLING DNS RESOLUTION FOR PI-HOLE NOW!
STEP 7: Using two Pi-holes in high-availability configuration with automatically synchronized configurations (using Gravity Sync)
If you want this video, let me know in the video’s comments!
Maintenance and Backup
Health check (from SSH)
[copy/paste >] pihole status[copy/paste >] systemctl status pihole-FTL --no-pagerUpdate all pieces periodically (from SSH) set a recurring monthly reminder!
[copy/paste >] sudo pihole -up[copy/paste >] sudo apt update && sudo apt full-upgrade -y[copy/paste >] sudo systemctl restart unboundExport/Import configuration (from Pi-hole Web UI) when you make changes
Web UI → Settings → Teleporter (and email yourself the backup)
