Pi-hole Installation & High Availability Guide#

1. Basic Installation#

Deployment#

# Automated install script
curl -sSL [https://install.pi-hole.net](https://install.pi-hole.net) | bash

Password Management#

Save the password provided at the end of the installation.

# To change or reset the web interface password:
pihole setpassword
# Alternative:
pihole -a -p

Network Integration (UniFi)#

Go to UniFi Network App > Internet > [Your WAN/LAN].
Change DNS Server to your Pi-hole IP.

2. Synchronization (Multi-Instance)#

For Pi-hole Version 6#

Use Nebula Sync for v6 compatibility.

Repository: lovelaze/nebula-sync

For Pi-hole Version 5#

Use Orbital Sync to keep lists in sync between master and slave.

Master Instance (Docker Compose):

version: "3"
services:
  orbital-sync:
    image: mattwebbio/orbital-sync:1
    restart: unless-stopped
    environment:
      PRIMARY_HOST_BASE_URL: [http://10.1.2.108](http://10.1.2.108)
      PRIMARY_HOST_PASSWORD: private
      SECONDARY_HOSTS_1_BASE_URL: [http://10.1.2.128](http://10.1.2.128)
      SECONDARY_HOSTS_1_PASSWORD: private
      INTERVAL_MINUTES: 60

Slave Instance (Reverse Sync):

version: "3"
services:
  orbital-sync:
    image: mattwebbio/orbital-sync:1
    environment:
      PRIMARY_HOST_BASE_URL: [http://10.1.2.128](http://10.1.2.128)
      PRIMARY_HOST_PASSWORD: private
      SECONDARY_HOSTS_1_BASE_URL: [http://10.1.2.188](http://10.1.2.188)
      SECONDARY_HOSTS_1_PASSWORD: private
      INTERVAL_MINUTES: 60

3. High Availability with Keepalived#

This setup creates a Virtual IP (10.1.2.8) that floats between two nodes.

Installation#

apt install keepalived -y

Node 1: Master Configuration#

nano /etc/keepalived/keepalived.conf

vrrp_instance pihole {
  state MASTER
  interface eth0
  unicast_src_ip 10.1.2.100
  unicast_peer {
    10.1.2.101
  }
  virtual_router_id 1 
  priority 100
  advert_int 1
  authentication {
    auth_type PASS
    auth_pass ZNC9mjp@
  }
  virtual_ipaddress {
    10.1.2.8/24
  }
}

Node 2: Backup Configuration#

nano /etc/keepalived/keepalived.conf

vrrp_instance pihole {
  state BACKUP
  interface eth0
  unicast_src_ip 10.1.2.101
  unicast_peer {
    10.1.2.100
  }
  virtual_router_id 1 
  priority 50 
  advert_int 1
  authentication {
    auth_type PASS
    auth_pass ZNC9mjp@
  }
  virtual_ipaddress {
    10.1.2.8/24
  }
}

Service Management#

# Enable and Start
systemctl enable keepalived && systemctl start keepalived

# Check Status
systemctl status keepalived

# Apply Changes
systemctl restart keepalived