chore: initial import from KNEL/PFVCluster@041d311 [#769]

Split per O&M lane work order. Full history: KNEL/PFVCluster. https://projects.knownelement.com/issues/769#note-4152
2026-09-03 21:30:32 -05:00
commit 33827de0dc
236 changed files with 9587 additions and 0 deletions
@@ -0,0 +1,3 @@
+# Pi-hole web UI password. NEVER commit the real .env — only this template.
+# Copy to .env and set the value before `docker compose up -d`.
+PIHOLE_WEB_PASSWORD=changeme
@@ -0,0 +1,10 @@
+# netinfra/pihole/README.md
+
+> **Documentation moved to Discourse — the canonical source of truth.**
+>
+> **Pi-hole recursive DNS hardening**
+>
+> **Read it here:** https://community.turnsys.com/t/306
+>
+> *Migrated 2026-08-06. This file is kept as a pointer for git-browsing context.
+> Do not update content here — edit the Discourse wiki topic instead.*
@@ -0,0 +1,60 @@
+services:
+  pihole:
+    container_name: pihole
+    # Root cause of the 2026-08 gravity.db corruption: default /dev/shm (64M)
+    # was too small for FTL's shared-memory metrics. 1024M has been stable.
+    shm_size: '1024M'
+    image: pihole/pihole:2026.07.0
+    hostname: pihole
+    entrypoint: ["/usr/local/bin/gravity-validate.sh"]
+    ports:
+      - "53:53/tcp"
+      - "53:53/udp"
+      - "10002:80/tcp"
+      - "10003:443/tcp"
+    environment:
+      TZ: 'America/Chicago'
+      FTLCONF_webserver_api_password: '${PIHOLE_WEB_PASSWORD}'
+      FTLCONF_dns_listeningMode: 'all'
+      # Rate-limiting disabled (count=0). Uptime Kuma on Cloudron VPS sends
+      # high-volume DNS queries for monitoring; default 1000/60s limit was
+      # causing intermittent REFUSED responses → Uptime Kuma flapping.
+      FTLCONF_dns_rateLimit_count: '0'
+      FTLCONF_dns_rateLimit_interval: '0'
+      FTLCONF_dns_upstreams: '["8.8.8.8"]'
+      # Conditional forwarding: knel.net + 100.64/10 + 192.168/16 all go to
+      # this node's Technitium (tsys-dns) over the shared dnsnet bridge —
+      # Technitium is the single source of truth for knel.net zones. Set
+      # live 2026-08-26 [#449]; mirrored here so recreation keeps it.
+      FTLCONF_dns_revServers: '["true,100.64.0.0/10,10.53.0.53,knel.net","true,192.168.0.0/16,10.53.0.53"]'
+    volumes:
+      - './etc-pihole:/etc/pihole'
+      - './etc-dnsmasq.d:/etc/dnsmasq.d'
+      - './gravity-validate.sh:/usr/local/bin/gravity-validate.sh:ro'
+    cap_add:
+      - SYS_NICE
+    restart: always
+    healthcheck:
+      test: ["CMD-SHELL", "dig +short +norecurse @127.0.0.1 pi.hole >/dev/null 2>&1 && test -s /etc/pihole/gravity.db || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+    labels:
+      autoheal: "true"
+    networks:
+      - default
+      - dnsnet
+  autoheal:
+    container_name: autoheal
+    image: willfarrell/autoheal:1.2.0
+    environment:
+      AUTOHEAL_CONTAINER_LABEL: autoheal
+      AUTOHEAL_INTERVAL: 30
+      AUTOHEAL_START_PERIOD: 60
+    volumes:
+      - '/var/run/docker.sock:/var/run/docker.sock:ro'
+    restart: always
+networks:
+  dnsnet:
+    external: true
@@ -0,0 +1,28 @@
+#!/bin/bash
+# gravity-validate.sh — pre-start integrity check for Pi-hole's gravity.db
+#
+# Runs as the container entrypoint. If gravity.db is empty or has an invalid
+# SQLite header (the symptom of the /dev/shm corruption outage), move it aside
+# so Pi-hole regenerates a clean DB on start instead of crashing.
+set -e
+GRAVITY_DB="/etc/pihole/gravity.db"
+TIMESTAMP=$(date +%Y%m%d%H%M%S)
+
+if [ -f "$GRAVITY_DB" ]; then
+    if [ ! -s "$GRAVITY_DB" ]; then
+        echo "[gravity-validate] gravity.db is empty, moving aside"
+        mv "$GRAVITY_DB" "${GRAVITY_DB}.corrupt.${TIMESTAMP}"
+    else
+        HEADER=$(head -c 15 "$GRAVITY_DB" 2>/dev/null || true)
+        if [ "$HEADER" != "SQLite format 3" ]; then
+            echo "[gravity-validate] gravity.db invalid header, moving aside"
+            mv "$GRAVITY_DB" "${GRAVITY_DB}.corrupt.${TIMESTAMP}"
+        fi
+    fi
+fi
+# Keep only the 3 most recent corrupt backups (names carry a timestamp,
+# so lexical reverse-sort = newest-first).
+find /etc/pihole -maxdepth 1 -name 'gravity.db.corrupt.*' -print 2>/dev/null \
+  | sort -r | tail -n +4 | xargs -r rm -f
+echo "[gravity-validate] OK, starting Pi-hole"
+exec /usr/bin/start.sh "$@"