Home Pi-hole setup with High Availablity

Pi-hole setup with High Availablity

This is a step by step guide to set up Pi-hole in a high availabilty environment. Previously I was using a lone Raspberry Pi 3B to run Pi-hole. The issue with this setup was, if that pi went down, DNS was down on my network, which is definitely unacceptable. So let make it better!


Since I am running this in a Proxmox LXC, I need to install curl and rsync. A more typical debian or ubuntu install should already have these utilities installed.

sudo apt update && apt upgrade -y && apt install curl rsync -y

Once curl is install, I can continue with the install.

Installing Pi-hole

I prefer to run Pi-hole natively as an application, rather than in Docker. To do this I typically follow their official install documentation. Basically though, it boils down to running this command with sudo.

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

When you run the install command, a GUI will appear. It will guide you through the install process. Remember you will need to have a static IP to correctly host Pi-hole, so either set that in your environment, or use a static DHCP reservation. I use the default settings for the rest of the install and once it is complete, I always reset the password for the Pi-hole admin panel using the following command.

pihole -a -p

Lastly, you’ll want to add your user to the pihole group so that you can edit configuration files without needing sudo. This will be useful later.

sudo usermod -a -G pihole <username>

Configuring Pi-hole

Always enable dark mode in Settings > API / Web interface > Web interface settings.

Because my network sets DNS per client, and not just per gateway, each client will make DNS requests directly to my Pi-hole instance. This is better for logging, but means that Pi-hole needs to be behind a firewall, and must permit all origins. This can be configured in Settings > DNS > Interface Settings

systemctl status keepalived

I also like to turn on DNSSEC in Settings > DNS > Advanced DNS settings. This will add a little extra assurance on DNS lookups.

systemctl status keepalived

Redirect to Admin

The last change that I make is to redirect HTTP requests to the root path to the pihole /admin path. I find it annoying this isn’t done by default but it’s an easy fix. Simply add the following line to the lighttpd.conf file.

sudo nano /etc/lighttpd/lighttpd.conf
url.redirect = ("^/$" => "/admin" )

High Availability with keepalived

To have a high availabilty cluster, you will need more than one Pi-hole instance running. Once you have them both running, you can configure keepalived to set up a virtual IP between them using a technology called VRRP. It allows both servers to share a virtual IP between them, swapping instantly when one of them goes down. Because this is more of a “hot spare” methodology, one node will be primary, and the rest will be secondary. To get started you will need to install two pacakges.

sudo apt install keepalived libipset13 -y

Once installed, edit the configuration file

sudo nano /etc/keepalived/keepalived.conf

Here’s an example of the configuration file. Let’s break it down.

vrrp_instance pihole {
  interface ens18
  virtual_router_id 30
  priority 150
  advert_int 1
  unicast_peer {

  authentication {
    auth_type PASS
    auth_pass <password>

  virtual_ipaddress {
1The first thing to configure is the instance name. I have it set to pihole.
2You will need to decide the node’s default disposition, whether it is the master node or a backup. Keep in mind, the node’s disposition will change as necessary based on other nodes. If another node enters the cluser with a higher priorty, it will always become the master node.
3The name of the interface that the virtual IP will be bound. Can be found using ip a.
5The priority will configure which node is the Master. The master node will always be the node with the highest priority
6The advertisement timespan in seconds.
7You will need to add the node’s IP
8The other nodes IPs

Never set an IP reservation for the virtual IP, or set it as a static address for another device

Also keep in mind, this is set up for unicast, but can be configured for multicast. I just like to be explict. You can find more details about keepalived configuration here.

Once it’s configured, restart the service

sudo systemctl restart keepalived

You can check the service with the following command also

sudo systemctl status keepalived

systemctl status keepalived

Configuring Local DNS

I use Pi-hole as my local DNS service also, so I will need to add my local DNS records. This can be done in the web admin panel at Local DNS > DNS Records, but for initial configuration, it is quicker to add records to the custom.list file. This is for A/AAAA records only.

sudo nano /etc/pihole/custom.list

Records are added as ip hostname

5 proxmox.local pihole.local pihole1.local pihole2.local pihole3.local

CNAME records can be edited using the web admin panel at Local DNS > CNAME Records, or manually in a different file in dnsmasq.d

sudo nano /etc/dnsmasq.d/05-pihole-custom-cname.conf

Entries here will follow a different format: cname:<alias>,<a-record>


Syncronizing Local DNS

Now, a critical part of this is that the configuration you set up on your primary node is distributed to the other nodes, so that in the event of a failover your DNS local records still resolve. If you don’t use local DNS, or want to keep things syncronized manually, you can skip this bit. If not though, I’ll show you how to syncronize these files using Gravity Sync.

In the past I tried to keep instances syncronized with rsync, but that proved to be too fragile over time. Gravity sync does a very robust job and just works.

To install, follow the installation guide in the repo, but to overview you will need to run the curl command.

curl -sSL https://raw.githubusercontent.com/vmstan/gs-install/main/gs-install.sh | bash

The install script will prompt you for the remote machine. For my usage, my auxiallary instances pull their configuration from the primary instance. Once a connection is made, run the pull command.

gravity-sync pull

Then you can configure it to run automatically by running the automate command.

gravity-sync auto

Auto will follow use the last successful connection made, pull or push.

Congratulations, you should now have a high availabilty Pi-hole cluster!

This post is licensed under CC BY 4.0 by the author.