Deploying Pi-hole v6 Offline on Proxmox VE with a Palo Alto Firewall

🏗️ Technical Architecture Overview

• • Hypervisor: Proxmox VE (PVE)
  • Parent Compute Layer: Privileged Linux Container (LXC) running a minimal Debian 12 base template.
  • Network Blueprint: Bound to vmbr1, isolated natively via VLAN 7 (172.16.7.2/24), routing through gateway 172.16.7.1.
  • Runtime Engine: Decoupled, standalone static binary installation of Docker Engine v27.3.1.
  • Application Tenant: Pi-hole v6 running in native Host Networking Mode (--net=host).
  • Upstream Security: Border perimeter managed by a Palo Alto Networks (PAN) Layer 7 firewall with strict application checking and URL filtering.

🛑 Phase 1: Perimeter Firewall Provisioning (Palo Alto)

1. 1. Custom URL Category Object: Created an object named Pihole-Gravity-Sources populated with explicit domains to pull source databases:
      • • *.github.com
        • *.githubusercontent.com
        • *.pi-hole.net
        • install.pi-hole.net

   2. Security Policy Mapping:
      • • Source: VLAN 7 Zone (172.16.7.2)
        • Destination: WAN/External Zone (any)
        • Applications Permit List: ssl, web-browsing, dns, github-base (Crucial: required to pass deep inspection chunking packets during data stream ingestion).
        • Service Profile: Standard ports 80/http and 443/https.
        • URL Category Constraint: Enforced to match Pihole-Gravity-Sources.

💾 Phase 2: Staging Offline Files (Management PC)

1. 1. PVE Debian 12 Template:
      Index of /images/system/
   2. Docker Standalone Core:
      Index of linux/static/stable/x86_64/
   3. Pi-hole v6 Docker Image: Pulled down via an archive generator engine as a clean deployment container tarball (pihole-pihole-latest-linux-amd64.image.tar).

🛠️ Phase 3: Parent LXC Deployment & Pre-Staging

1. 1. Create the Parent Host:

      pct create 105 /mnt/pve/mass-storage/template/cache/debian-12-standard_12.7-1_amd64.tar.zst \
        -cores 1 \
        -memory 1024 \
        -swap 512 \
        -ostype debian \
        -storage mass-storage \
        -rootfs mass-storage:8 \
        -unprivileged 0 \
        -features nesting=1 \
        -onboot 1 \
        -net0 name=eth0,bridge=vmbr1,tag=7,ip=172.16.7.2/24,gw=172.16.7.1 \
        -nameserver 1.1.1.1
      

   2. Mount the Raw Virtual Disk for Staging:

      pct mount 105
      

   3. Decompress and Inject Standalone Docker Binaries into System Paths:

      tar -xf /mnt/pve/mass-storage/template/cache/docker-27.3.1.tgz -C /var/lib/lxc/105/rootfs/usr/bin/ --strip-components=1
      

   4. Decompress and Inject Pi-hole Image Template:

      tar -xf /mnt/pve/mass-storage/template/cache/pihole-pihole-latest-linux-amd64.image.tar.gz -C /var/lib/lxc/105/rootfs/root/
      

   5. Close and Fire Up Compute Layer:

      pct unmount 105
      pct start 105
      

🐳 Phase 4: Initializing Engine Layers (Inside Container Shell)

1. 1. Fix Missing Host Constraints:
      groupadd docker
      apt-get update && apt-get install -y nftables
      
   2. Mitigate Missing Network Engine Elements (iptables Bypass JSON Config):
      Because the thin container lacked the legacy iptables stack, we commanded Docker to use a hypervisor-safe block driver storage matrix and turn off firewall manipulation:

      mkdir -p /etc/docker
      cat << 'EOF' > /etc/docker/daemon.json
      {
        "exec-opts": ["native.cgroupdriver=cgroupfs"],
        "storage-driver": "vfs",
        "iptables": false
       }
      EOF
      

   3. Start Core Engine Systems:

      dockerd > /var/log/dockerd.log 2>&1 &
      

   4. Ingest Web Registry Layouts:

      docker load -i /root/pihole-pihole-latest-linux-amd64.image.tar
      

🎯 Phase 5: Executing the Pi-hole v6 Application Tenant

1. 1. The Live Run Sequence:

      docker run -d \
        --name=pihole \
        --net=host \
        -e TZ="America/Chicago" \
        -e FTLCONF_webserver_api_password="WebLoginPasswordHere" \
        -e FTLCONF_dns_listeningMode="ALL" \
        -e FTLCONF_dns_upstreams="1.1.1.1;9.9.9.9" \
        -v pihole_config:/etc/pihole \
        -v dnsmasq_config:/etc/dnsmasq.d \
        --restart=unless-stopped \
        pihole/pihole:latest
      

      • • --net=host: Bypassed broken virtual bridge layers, mapping directly to VLAN 7 network cards.
        • FTLCONF_webserver_api_password: Resolved the deprecated WEBPASSWORD v5 variable problem.
        • FTLCONF_dns_listeningMode="ALL": Opened cross-subnet resolution rules, allowing external VLAN query targets.
        • FTLCONF_dns_upstreams: Seaded upstream parameters to prevent silent drops.

🔒 Phase 6: Core System Persistence (Automation on Boot)

cat << 'EOF' > /etc/init.d/docker
#!/bin/sh
### BEGIN INIT INFO
# Provides:          docker
# Required-Start:    $network $remote_fs
# Required-Stop:     $network $remote_fs
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Start Docker Daemon
### END INIT INFO

case "$1" in
  start)
    echo "Starting Docker Daemon..."
    # Carve runtime networks back into memory paths
    nft add table inet filter 2>/dev/null
    nft add chain inet filter input { type filter hook input priority 0 \; policy accept \; } 2>/dev/null
    nft add rule inet filter input udp dport 53 accept 2>/dev/null
    nft add rule inet filter input tcp dport 53 accept 2>/dev/null
    # Run core daemon engine
    /usr/bin/dockerd > /var/log/dockerd.log 2>&1 &
    ;;
  stop)
    echo "Stopping Docker Daemon..."
    killall dockerd
    ;;
  restart)
    $0 stop
    sleep 2
    $0 start
    ;;
  *)
    echo "Usage: $0 {start|stop|restart}"
    exit 1
    ;;
esac
exit 0
EOF

chmod +x /etc/init.d/docker
update-rc.d docker defaults