A Pi-hole secondary server doesn’t just mirror the primary; it actively participates in DNS resolution, making your network’s name resolution surprisingly resilient even if the primary goes offline.
Let’s see it in action. Imagine your network’s DNS requests are pointed to 192.168.1.10 (your primary Pi-hole).
dig google.com @192.168.1.10
If 192.168.1.10 is working, you get a speedy response. Now, if you configure a secondary Pi-hole at 192.168.1.11 and point your clients to both IP addresses (e.g., in your router’s DHCP settings for DNS servers), here’s what happens when you query the secondary:
dig google.com @192.168.1.11
You’ll get the same answer. The magic isn’t just that it can answer, but that it’s synchronized. The pihole --sync-gravity command is the key here, usually run on the primary and then triggered on the secondary. On the primary:
sudo pihole --sync-gravity
This command pulls the latest blocklists, updates the gravity database, and prepares it for transfer. On the secondary, you’d typically have a cron job or manually run:
sudo pihole --sync-gravity
This pulls the updated gravity from the primary. The actual DNS resolution happens because the secondary Pi-hole, when queried, performs the same lookup process as the primary: it checks its cache, then consults upstream DNS servers if necessary. The redundancy comes from having two independent systems capable of doing this, with their configurations kept in sync.
The problem this solves is single point of failure for your network’s DNS. Without it, if your primary Pi-hole box crashes, reboots unexpectedly, or its network interface fails, your clients lose internet connectivity because they can’t resolve domain names. By adding a secondary, your clients can still query a working DNS server even if the primary is down.
Internally, the setup relies on two core mechanisms:
- Gravity Synchronization: The
gravitydatabase contains all the adlists and their compiled domains. Keeping this synchronized ensures both Pi-holes are blocking the same things and have the same known good domains. - DHCP Configuration: Clients are configured via DHCP to use multiple DNS servers. When a client needs to resolve a domain, it sends the query to the first DNS server listed in its configuration. If that server responds, the client uses the answer. If it doesn’t respond within a timeout period, the client will try the next DNS server in the list. This "failover" behavior is crucial.
The levers you control are primarily:
- IP Addresses: Assign static IP addresses to both your primary and secondary Pi-hole servers.
- Upstream DNS Servers: Configure identical upstream DNS servers on both Pi-holes. This ensures consistent resolution results.
- Synchronization Schedule: Decide how often to sync gravity. For most home networks, once a day is sufficient. For high-traffic or rapidly changing environments, more frequent syncs might be needed.
- Client DHCP Configuration: Set your router’s DHCP server to hand out the IP addresses of both your primary and secondary Pi-hole servers as the DNS servers for your clients. The order matters for initial failover speed, but both must be present.
The most surprising part of this setup is how little actual "secondary" configuration is needed on the second Pi-hole itself. You don’t configure it to listen for commands from the primary in a special way; you just set it up as a standard Pi-hole instance and then ensure its gravity database is kept up-to-date with the primary. The failover mechanism is entirely handled by the clients and their network configuration, relying on standard DNS client behavior when presented with multiple servers.
The next logical step is to consider how to monitor the health of both your primary and secondary Pi-hole instances and to automate the gravity sync process reliably.