Self-hosting Pi-hole on Your Own VPS

Why Self-host Pi-hole on a VPS

Concrete benefits of Pi-hole on a VPS

• Universal protection: covers all your devices (PCs, phones, tablets) without per-device configuration
• Bandwidth reduction: blocked requests consume zero download bytes
• Centralized DNS logs: full visibility on domains contacted by each device
• ISP independence: your DNS no longer transits through your ISP's resolver
• IoT tracker blocking: connected devices cannot contact their telemetry servers
• Customizable: add your own rules, whitelist what you need, choose your lists

Pi-hole v5 vs Pi-hole v6: What Changed

Pi-hole v5 vs v6

Scroll the table

Technical Requirements

What you need

• A VPS running Ubuntu 22.04/24.04 or Debian 12 with at least 512 MB RAM (1 GB recommended)
• A static IPv4 address and ideally an IPv6 address
• Root or sudo SSH access
• Port 53 (TCP and UDP) closed to the Internet: open only to the WireGuard interface or to your own IP addresses, never to everyone
• Port 80 or 443 for the web interface (optional but recommended with HTTPS)

Security first: no open resolver, and tracked updates

Deploy Pi-hole Step by Step

Full installation on Ubuntu/Debian

1. 01

   Disable the systemd-resolved stub resolver

   On recent Ubuntu and Debian, systemd-resolved listens on port 53 locally. Pi-hole cannot start while this port is taken. Edit /etc/systemd/resolved.conf and add DNSStubListener=no under the [Resolve] section. Then reload: sudo systemctl reload systemd-resolved. Verify the port is free: ss -tulpn | grep ':53'.

2. 02

   Install Pi-hole

   Run the official script:

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

   The installer asks for the network interface (often eth0) and the upstream DNS (pick Custom if you will install Unbound afterwards). Keep the default listening mode, “Allow only local requests”: with WireGuard, it is the right one. Note the admin password shown at the end, or set it with pihole setpassword.

3. 03

   Configure the firewall

   Do not open port 53 to the whole Internet. Open the WireGuard port, allow DNS from the tunnel subnet, and deny the rest:

   sudo ufw allow 51820/udp
   sudo ufw allow from 10.8.0.0/24 to any port 53
   sudo ufw deny 53

   Adjust 10.8.0.0/24 to your tunnel's subnet. If you use CSF or firewalld, translate the same rules. The web interface must not be public either: go through the tunnel or through an HTTPS reverse proxy restricted to your IPs.

4. 04

   Check that it works

   Test resolution, then blocking, from the VPS itself; then check from outside that the port cannot be reached outside the tunnel:

   # from the VPS
   dig @127.0.0.1 google.com
   dig @127.0.0.1 doubleclick.net
   # from an outside machine, OUTSIDE the tunnel: must fail
   nmap -sU -p 53 IP_DE_VOTRE_VPS

   google.com must return an address, doubleclick.net must answer 0.0.0.0, and nmap must show the port as closed or filtered.

5. 05

   Point your devices at the VPS

   The simplest path is WireGuard: in each client's configuration, set Pi-hole's tunnel address as the DNS server, following the Pi-hole WireGuard guide:

   [Interface]
   Address = 10.8.0.2/32
   DNS = 10.8.0.1

   On Android, “Private DNS” does not fit: it expects the hostname of a DNS-over-TLS provider, not an IP address (see Android help), and Pi-hole does not serve encrypted DNS. On iOS and on desktops, the WireGuard app applies the same DNS line. The tunnel also protects you on 4G and public Wi-Fi.

6. 06

   Open the web interface

   In v6, the interface is served by FTL itself at http://IP/admin (and over HTTPS with a self-signed certificate). Open it through the tunnel, for example http://10.8.0.1/admin, and log in with the password set during install. The dashboard shows live query counts, block rate, most requested domains and most active clients.

Adding Recommended Blocklists

Recommended lists

• StevenBlack Unified (ads + trackers): https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts — the reference, ~100,000 domains
• OISD Big: https://big.oisd.nl — aggressive list but few false positives, ~500,000 domains
• Firebog Ticked (green checkmark only): visit firebog.net and only add green-ticked lists to minimize false positives
• HaGeZi Multi PRO: https://raw.githubusercontent.com/hagezi/dns-blocklists/main/adblock/pro.txt — excellent malware coverage
• Perflyst Smart-TV: to block telemetry from smart TVs

Managing False Positives and Whitelisting

Diagnosing and fixing a false positive

1. 07

   Identify the blocked domain

   In the interface, open Query Log (real-time) or Long-term data → Query Log. Filter by client or by Blocked status. Each entry shows the exact domain and the list that blocked it. In v6, you can click on an entry to see full details.

2. 08

   Add to the allowlist

   Click the domain and then Allow, or go to Domains and add it as type Allow. To allow a domain and all its subdomains, use the Wildcard option. An allowed entry always wins over blocklists. If the same false positive keeps coming back across many domains, subscribe instead to a community-maintained allowlist under Lists, as type Allow.

3. 09

   Allow from the command line

   v6 renamed the commands: pihole -w and --white-wild no longer exist. Over SSH:

   pihole allow example.com
   pihole --allow-wild example.com
   pihole allow -l

   The first allows an exact domain, the second the domain and its subdomains, the third lists the allowlist.

4. 10

   Common false positive cases

   Microsoft Teams and Office 365 sometimes block on aggressive lists (live.com, microsoft.com domains). Apple uses CDNs shared with trackers. Windows automatic updates may be blocked by some lists. The firebog.net green list exists precisely to reduce these issues.

Pi-hole in Docker, and port 53 conflicts

Deploy Pi-hole with Docker Compose and plug your containers into it

1. 11

   Write the docker-compose.yml

   The file follows the Pi-hole Docker documentation, with a dated tag rather than latest so you control updates. DNS is only published on loopback and on the Docker bridge address 172.17.0.1, never on the public IP; the web interface only on 127.0.0.1:8080, for a reverse proxy.

   mkdir -p /opt/pihole/etc-pihole && cd /opt/pihole
   cat > docker-compose.yml << 'EOF'
   services:
     pihole:
       container_name: pihole
       image: pihole/pihole:2026.10.1
       ports:
         - "127.0.0.1:53:53/tcp"
         - "127.0.0.1:53:53/udp"
         - "172.17.0.1:53:53/tcp"
         - "172.17.0.1:53:53/udp"
         - "127.0.0.1:8080:80/tcp"
       environment:
         TZ: 'Europe/Paris'
         FTLCONF_webserver_api_password: 'a-long-password'
         FTLCONF_dns_listeningMode: 'ALL'
         FTLCONF_dns_upstreams: '9.9.9.9;1.1.1.1'
       volumes:
         - './etc-pihole:/etc/pihole'
       restart: unless-stopped
   EOF
   docker compose up -d && docker compose logs pihole | tail -20

   FTLCONF_dns_listeningMode: 'ALL' is required on the bridge network, because queries arrive from outside the container's subnet; the port mapping is what prevents public exposure. Add cap_add: NET_ADMIN only if Pi-hole also serves DHCP, which makes no sense on a VPS.

2. 12

   Plug the other containers into Pi-hole

   In each service of your other stacks, set the Docker bridge address:

   services:
     my-app:
       image: my-image
       dns:
         - 172.17.0.1

   Do not write 127.0.0.1: Docker's documentation points out that, in a container, --dns=127.0.0.1 refers to the container's own loopback, not the host's. For a global setting, the same address goes into /etc/docker/daemon.json under the dns key, followed by systemctl restart docker.

3. 13

   Check that no other process is listening

   Diagnostic command: sudo ss -tulpn | grep ':53'. The only expected process is pihole-FTL (or docker-proxy for ports published by the container). If you see systemd-resolved, named or bind9, disable the competing service. For systemd-resolved, DNSStubListener=no in /etc/systemd/resolved.conf is enough, as on a native install.

4. 14

   Check the resolver a container sees

   From a container, read its DNS configuration:

   docker exec my-app cat /etc/resolv.conf
   sudo ss -tulpn | grep ':53'

   A container on a custom Compose network shows 127.0.0.11, Docker's embedded resolver, which forwards to the declared dns: servers: that is normal. The proof is in Pi-hole's Query Log, where the container must appear as a client. If the Gravity update fails with “Could not access the internet”, the Pi-hole container is probably resolving through itself in a loop: check that FTLCONF_dns_upstreams targets an external resolver or Unbound.

Pi-hole + Unbound: Full DNS Recursion Without a Third Party

Installing and configuring Unbound

1. 15

   Install Unbound

   sudo apt install unbound. Unbound is available in official Ubuntu and Debian repositories. It starts automatically but we'll configure it to listen locally only.

2. 16

   Create the Pi-hole + Unbound configuration

   Create /etc/unbound/unbound.conf.d/pi-hole.conf from the configuration in the Pi-hole Unbound guide: listening on 127.0.0.1 port 5335, DNSSEC hardening, EDNS buffer at 1232 bytes.

   sudo tee /etc/unbound/unbound.conf.d/pi-hole.conf > /dev/null << 'EOF'
   server:
       verbosity: 0
       interface: 127.0.0.1
       port: 5335
       do-ip4: yes
       do-udp: yes
       do-tcp: yes
       do-ip6: no
       harden-glue: yes
       harden-dnssec-stripped: yes
       edns-buffer-size: 1232
       prefetch: yes
   EOF
   sudo systemctl restart unbound

   Installed from the Debian or Ubuntu repositories, Unbound already knows the root servers: downloading root.hints from internic.net is only useful for a hand-compiled install.

3. 17

   Point Pi-hole to Unbound

   In the Pi-hole interface, go to Settings → DNS. Uncheck all upstream DNS servers. In the Custom DNS field, enter 127.0.0.1#5335. Save. Pi-hole will now send all unblocked queries to Unbound, which resolves them directly from root servers.

4. 18

   Check recursion and DNSSEC

   Test Unbound directly:

   dig pi-hole.net @127.0.0.1 -p 5335
   dig fail01.dnssec.works @127.0.0.1 -p 5335
   dig +ad dnssec.works @127.0.0.1 -p 5335

   The first query must return an address. The second must fail with SERVFAIL and no address: the domain's signature is deliberately broken. The third must answer NOERROR with the ad flag, which confirms DNSSEC validation. In Pi-hole's Query Log, queries must show as forwarded to 127.0.0.1#5335.

5. 19

   Neutralise openresolv on Debian

   Debian installs openresolv by default, and the unbound-resolvconf service then writes nameserver 127.0.0.1 without port 5335 into /etc/resolv.conf: the system queries Pi-hole, which queries Unbound, which is no longer reached. The Pi-hole Unbound guide recommends disabling that service:

   sudo systemctl disable --now unbound-resolvconf.service
   # then comment out the unbound_conf= line in /etc/resolvconf.conf

   Then restart Unbound and rerun the tests from the previous step.

Monitoring Pi-hole Metrics

Important metrics and reference values

• Blocking rate (Ads blocked today): between 10% and 30% is normal. A rate below 5% suggests your lists are incomplete. A rate above 40% may indicate too many false positives.
• Queries/24h: gives an idea of the load. A family network typically generates 5,000 to 50,000 queries per day.
• Top Blocked Domains: if an ad domain tops the list every day, the corresponding app is particularly intrusive.
• Top Clients: identify the most talkative devices — IoT objects are often at the top.
• DNS cache size: in v6, FTL manages the internal cache. A high hit rate (>60%) reduces perceived latency.
• Query Types: an abnormal volume of PTR (reverse resolution) queries may indicate a network scan or misconfigured software.

Pi-hole v6 or AdGuard Home?

Pi-hole v6 and AdGuard Home, criterion by criterion

Scroll the table

Backing Up and Restoring Pi-hole Configuration

Backup and restore

1. 20

   Create a Teleporter backup

   In the web interface, open Settings → Teleporter and export the archive: Pi-hole generates a ZIP file with the configuration, lists, groups and allowed or blocked domains. On the command line, v6 goes through the FTL binary:

   mkdir -p /root/pihole-backups && cd /root/pihole-backups
   sudo pihole-FTL --teleporter

   The archive is created in the current directory, and its name is printed.

2. 21

   Automate the backup

   Add these two jobs with crontab -e: one archive every night, and cleanup of archives older than 30 days.

   0 2 * * * cd /root/pihole-backups && pihole-FTL --teleporter >/dev/null 2>&1
   0 3 * * * find /root/pihole-backups -name '*.zip' -mtime +30 -delete

   With Docker, prefix the command with docker exec pihole and write the archive to the mounted volume, for example /etc/pihole.

3. 22

   Restore from a backup

   After a reinstall, open Settings → Teleporter and import your ZIP file, or use the command line:

   sudo pihole-FTL --teleporter /root/pihole-backups/ARCHIVE.zip

   Pi-hole imports settings, groups and lists. In v6 the Teleporter format differs from v5: v5 backups are only partly restored (lists imported, network configuration to redo by hand).

4. 23

   Back up Unbound configuration

   If using Unbound, add its files to your backup: tar -czf /root/unbound-config-$(date +%Y%m%d).tar.gz /etc/unbound/. Unbound configuration doesn't change between versions and can be restored directly.