cal/claude-home
1
0
Fork 0
Code Issues 6 Pull Requests 4 Actions Packages Projects Releases Wiki Activity
a5d019eb3f
claude-home/networking/pihole-ha-deployment-notes.md
Cal Corum 6c8d199359 Add Pi-hole HA documentation and networking updates 
Add dual Pi-hole high availability setup guide, deployment notes, and
disk optimization docs. Update NPM + Pi-hole sync script and docs.
Add UniFi DNS firewall troubleshooting and networking scripts CONTEXT.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-07 22:19:56 -06:00

7.3 KiB
Raw Blame History

Pi-hole HA Deployment Notes - 2026-02-06

Deployment Summary

Successfully deployed dual Pi-hole high availability setup with the following configuration:

Infrastructure

Primary Pi-hole (npm-pihole)

  • Host: 10.10.0.16 (LXC container)
  • Version: Pi-hole v6 (upgraded from v5.18.3)
  • Web UI: http://10.10.0.16:81/admin
  • Web Password: newpihole456
  • App Password: Stored in ~/.claude/secrets/pihole1_app_password
  • DNS Port: 53
  • Blocklists: 36 lists (restored from v5 backup)

Secondary Pi-hole (ubuntu-manticore)

  • Host: 10.10.0.226 (Physical server)
  • Version: Pi-hole v6.4
  • Web UI: http://10.10.0.226:8053/admin
  • Web Password: pihole123
  • App Password: Stored in ~/.claude/secrets/pihole2_app_password
  • DNS Port: 53
  • Note: systemd-resolved stub listener disabled

What's Working

✅ DNS Resolution

  • Both Pi-holes responding to DNS queries
  • Ad blocking functional on both instances
  • NPM custom DNS sync working (18 domains synced to primary)

✅ Network Configuration

  • Primary Pi-hole accessible network-wide
  • Secondary Pi-hole accessible network-wide
  • systemd-resolved conflicts resolved

✅ NPM Integration

  • npm-pihole-sync.sh script enhanced for dual Pi-hole support
  • Script located: /home/cal/scripts/npm-pihole-sync.sh on npm-pihole
  • Hourly cron configured
  • Syncs 18 proxy host domains to primary Pi-hole

Known Issues

⚠️ Orbital Sync Authentication Failing

  • Orbital Sync v1.8.4 unable to authenticate with Pi-hole v6
  • App passwords generated but login fails
  • Location: ~/docker/orbital-sync/ on ubuntu-manticore
  • Status: Needs further investigation or alternative sync solution

⚠️ Secondary Pi-hole NPM Domains

  • Custom DNS entries not synced to secondary yet
  • git.manticorum.com resolves to Cloudflare IPs on secondary
  • Primary resolves correctly to 10.10.0.16
  • Impact: Minimal for HA DNS, but local overrides only on primary

⚠️ Blocklists Not Synced

  • Primary has 36 blocklists restored from v5 backup
  • Secondary still has default lists only
  • Orbital Sync would handle this once authentication is fixed

v5 → v6 Upgrade Notes

Database Migration Issue

When upgrading Pi-hole from v5 to v6, the gravity database schema changed:

  • v5 database: 114MB with 36 adlists
  • v6 fresh database: 108KB with 1 default list

Resolution:

  1. Backup created automatically: gravity.db.v5.backup
  2. Adlists extracted from backup using Python sqlite3
  3. All 36 adlist URLs restored via web UI (comma-separated paste)

Lesson Learned: Always export adlists before major version upgrades

Authentication Changes

Pi-hole v6 uses app passwords instead of API tokens:

  • Generated via: Settings → Web Interface / API → Configure app password
  • Different from web login password
  • Required for API access and tools like Orbital Sync

Next Steps

Immediate

  1. ✅ Document app password locations (completed)
  2. ✅ Update .env.example files (completed)
  3. ✅ Update deployment documentation (completed)

Short Term

  1. Restore blocklists to secondary - Manually add 36 adlists via web UI
  2. Manually sync NPM domains to secondary - Update custom.list on secondary
  3. Update UniFi DHCP - Configure DNS1=10.10.0.16, DNS2=10.10.0.226
  4. Test failover - Verify DNS works when primary is down

Long Term

  1. Investigate Orbital Sync v6 compatibility - Check for updates or alternatives
  2. Consider manual sync script - Interim solution until Orbital Sync works
  3. Monitor Pi-hole v6 releases - Watch for stability updates

File Locations

Secrets

~/.claude/secrets/pihole1_app_password  # Primary app password
~/.claude/secrets/pihole2_app_password  # Secondary app password

Server Configs

server-configs/ubuntu-manticore/docker-compose/pihole/
server-configs/ubuntu-manticore/docker-compose/orbital-sync/
server-configs/networking/scripts/npm-pihole-sync.sh

Runtime Locations

npm-pihole:
  /home/cal/container-data/pihole/        # Primary Pi-hole data
  /home/cal/scripts/npm-pihole-sync.sh    # NPM sync script
  /home/cal/container-data/pihole/etc-pihole/gravity.db.v5.backup  # v5 backup

ubuntu-manticore:
  ~/docker/pihole/                        # Secondary Pi-hole
  ~/docker/orbital-sync/                  # Sync service (not working yet)

Blocklist URLs (36 total)

Comma-separated for web UI import:

https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts,https://blocklistproject.github.io/Lists/ads.txt,https://blocklistproject.github.io/Lists/abuse.txt,https://raw.githubusercontent.com/matomo-org/referrer-spam-blacklist/master/spammers.txt,https://someonewhocares.org/hosts/zero/hosts,https://raw.githubusercontent.com/VeleSila/yhosts/master/hosts,https://winhelp2002.mvps.org/hosts.txt,https://v.firebog.net/hosts/neohostsbasic.txt,https://raw.githubusercontent.com/RooneyMcNibNug/pihole-stuff/master/SNAFU.txt,https://paulgb.github.io/BarbBlock/blacklists/hosts-file.txt,https://v.firebog.net/hosts/static/w3kbl.txt,https://raw.githubusercontent.com/FadeMind/hosts.extras/master/add.Spam/hosts,https://raw.githubusercontent.com/PolishFiltersTeam/KADhosts/master/KADhosts.txt,https://v.firebog.net/hosts/Easyprivacy.txt,https://v.firebog.net/hosts/Prigent-Ads.txt,https://raw.githubusercontent.com/FadeMind/hosts.extras/master/add.2o7Net/hosts,https://raw.githubusercontent.com/crazy-max/WindowsSpyBlocker/master/data/hosts/spy.txt,https://hostfiles.frogeye.fr/firstparty-trackers-hosts.txt,https://hostfiles.frogeye.fr/multiparty-trackers-hosts.txt,https://www.github.developerdan.com/hosts/lists/ads-and-tracking-extended.txt,https://raw.githubusercontent.com/Perflyst/PiHoleBlocklist/master/android-tracking.txt,https://raw.githubusercontent.com/Perflyst/PiHoleBlocklist/master/SmartTV.txt,https://raw.githubusercontent.com/Perflyst/PiHoleBlocklist/master/AmazonFireTV.txt,https://gitlab.com/quidsup/notrack-blocklists/raw/master/notrack-blocklist.txt,https://raw.githubusercontent.com/DandelionSprout/adfilt/master/Alternate%20versions%20Anti-Malware%20List/AntiMalwareHosts.txt,https://osint.digitalside.it/Threat-Intel/lists/latestdomains.txt,https://s3.amazonaws.com/lists.disconnect.me/simple_malvertising.txt,https://v.firebog.net/hosts/Prigent-Crypto.txt,https://bitbucket.org/ethanr/dns-blacklists/raw/8575c9f96e5b4a1308f2f12394abd86d0927a4a0/bad_lists/Mandiant_APT1_Report_Appendix_D.txt,https://phishing.army/download/phishing_army_blocklist_extended.txt,https://gitlab.com/quidsup/notrack-blocklists/raw/master/notrack-malware.txt,https://raw.githubusercontent.com/Spam404/lists/master/main-blacklist.txt,https://raw.githubusercontent.com/FadeMind/hosts.extras/master/add.Risk/hosts,https://urlhaus.abuse.ch/downloads/hostfile/,https://v.firebog.net/hosts/Prigent-Malware.txt,https://v.firebog.net/hosts/Shalla-mal.txt

Testing Commands

# Test DNS on both Pi-holes
dig @10.10.0.16 google.com +short
dig @10.10.0.226 google.com +short

# Test ad blocking
dig @10.10.0.16 doubleclick.net +short  # Should return 0.0.0.0
dig @10.10.0.226 doubleclick.net +short  # Should return 0.0.0.0

# Test NPM custom DNS (primary only currently)
dig @10.10.0.16 git.manticorum.com +short  # Should return 10.10.0.16
dig @10.10.0.226 git.manticorum.com +short  # Currently returns Cloudflare IPs

# Check Pi-hole status
ssh cal@10.10.0.16 "docker exec pihole pihole status"
ssh ubuntu-manticore "docker exec pihole pihole status"