🌐 Nebula Sync
Nebula Sync is used to synchronize multiple Pi‑hole instances in this homelab, ensuring consistent blocklists, local DNS records, and configuration settings across all nodes.
⚠️ This is not a true high-availability cluster — it copies state on a scheduled or manual basis. Changes should always be made on the primary Pi‑hole.
⚙️ Purpose
Nebula Sync helps in environments where:
- You have multiple Pi‑hole servers for redundancy.
- You want consistent ad-blocking and DNS configurations across nodes.
- You need to automate syncing without manual export/import of Teleporter backups.
📦 Installation & Deployment
Nebula Sync is installed and configured using Ansible:
- Role: nebulasync_setup
- Deployment Playbook: deploy_nebulasync.yml
ansible-playbook -k -i inventory/dns/inventory.ini playbooks/dns/deploy_nebulasync.yml
🔹 Steps (Conceptual)
- Configure primary and replica Pi‑hole instances in the inventory.
- Apply the
nebulasync_setuprole using Ansible. - Verify sync configuration and schedules.
- Monitor logs and health checks to ensure successful propagation.
💡 Recommended to schedule syncs during off-peak hours to avoid DNS resolution delays.
🖥️ Configuration Overview
Primary → Replica model:
- Primary: Central source of truth; all changes made here.
- Replica: Receives configuration updates automatically via Nebula Sync.
What is synced:
- Gravity blocklists
- Whitelists and blacklists
- Regex filtering rules
- Local DNS entries
- Group and client assignments
- Pi‑hole configuration files
What is NOT synced:
- DHCP leases
- OS-level configuration
- Network interfaces
- UI-specific settings (themes, passwords if different)
- Custom scripts or plugins not installed on replicas
📝 DHCP remains authoritative on the existing DHCP server and is not shared between Pi-hole instances.
📡 Usage Notes
- Multiple replicas supported: Each replica points to a single primary.
- Sync verification: Check logs on both primary and replica after sync runs.
- Conflict avoidance: Avoid manual changes on replica nodes.
# Example: check Nebula Sync status
journalctl -u nebula-sync.service
📌 Best Practices
- Always edit primary Pi‑hole only.
- Enable logging for sync verification.
- Test sync after major updates or adding new blocklists.
- Monitor network connectivity between primary and replicas.
- Schedule regular sync intervals appropriate for the environment (e.g., hourly, daily).