[RELEASE] Pi-hole HA — automatic DHCP failover, VIP, and config sync for a Pi-hole cluster

General Customizing Pi-hole
, ,
33

I run two pihole instances here, both behind Unbound, and both peering with my NextDNS account upstream. The primary instance runs in a LXD container on a VM, and the secondary runs in a Docker container on a Pi4. Ignore the brief maintenance window below, the primary failed over as expected, to my secondary.

Screenshot 2026-07-19 at 12.50.50 PM
Screenshot 2026-07-19 at 12.50.50 PM672×800 66.1 KB

This covers my LAN, WAN, VPN and off-premises needs perfectly. I'm using Nebula to keep them sync'd, and a very small keepalived script that flips the VIP from one to the other, preferring the primary with some weighting.

vrrp_script chk_pihole {
    script "/etc/keepalived/check_pihole.sh"
    interval 2
    fall 2
    rise 2
    weight -150
}

vrrp_instance VI_DNS {
    state BACKUP
    interface enP3p49s0
    virtual_router_id 53
    priority 100
    advert_int 1

    authentication {
        auth_type PASS
        auth_pass [REDACTED]
    }

    virtual_ipaddress {
        192.168.4.5/22
    }

    track_script {
        chk_pihole
    }
}

Looking at Pi-Hole HA, I'm wondering how I could fold in the same capability, without a reinstall or compromising my current configuration, or its failover and failback.

Reading the above discussion, it's not an add-on, it's a complete rebuild and reinstall from scratch. Is that still the case?

34

Nice setup, and honestly for two nodes keepalived + a VIP weight is hard to beat - you’re not doing anything wrong here.

On the “reinstall from scratch” bit - lol no, wherever that impression came from, it’s not the case.

Pi-hole HA installs on top of an existing Pi-hole. The installer drops in its daemons and a small admin page, and doesn’t touch your Pi-hole config, DNS, Unbound, or your NextDNS peering. Nothing gets rebuilt.

It’s an add-on to Pi-hole, not an add-on to your HA stack. It wants to own the VIP and the config sync - the same two jobs keepalived and Nebula are already doing for you.

You can’t have two things fighting over the VIP, so folding it in really means swapping keepalived -> its VIP handling and Nebula -> its built-in sync, not layering it on top of them. No Pi-hole reinstall, but it does replace those two pieces.

Which leads to the real question: are you actually running Pi-hole as your DHCP server? You mentioned DNS, VIP and failover but not DHCP. If you’re not doing Pi-hole DHCP, the headline feature here - DHCP lease/reservation failover so leases survive a node going down - just doesn’t apply to you, and you’ve already got working VIP failover + sync. In that case there’s not much reason to switch. If you do want Pi-hole-managed DHCP with lease continuity across a failover, that’s exactly the gap it fills, since keepalived on its own won’t sync the lease database.

You can test install it tho, The installer defaults the VIP to off (you have to explicitly type “yes” to enable it), so installed that way it won’t fight keepalived for the VIP at all - it just monitors and gives you the dashboard.

One thing to remember, its config sync is on by default, so if you point the two nodes at each other as a cluster, one becomes the source of truth and pushes its config to the other within a few seconds.

So for a no-risk look, install it standalone (don’t peer them, or flip SYNC_ENABLED=false) and it stays hands-off. The flip side is that sync and VIP failover are exactly the parts that have to take the wheel to do their thing - there’s no “run the real failover but don’t touch my setup” mode, that’s just physics. Uninstall drops it cleanly and leaves your Pi-hole exactly as it was either way.

On your LXD-container-plus-Docker-Pi4 mix: Docker’s supported but has a couple of quirks, and I haven’t personally run it under LXD - so it should be fine, but I’m not going to promise that combo is flawless.