From 4aadef8e97a684c837b6fd8f70f6b9d75f97a21f Mon Sep 17 00:00:00 2001 From: beatzaplenty Date: Thu, 23 Jul 2026 12:35:30 +1000 Subject: [PATCH] docs: update documentation for debian-configuration repo rename - Root README.md: new, describes overall repo layout (proxmox/, pihole/, scripts/) and secret-scanning workflow - Root CLAUDE.md: new, cross-section guardrails and instructions for adding new machine types; references proxmox/CLAUDE.md and pihole/ section-specific rules - pihole/README.md: new, covers scripts usage, notable DHCP/PXE config, EFI VM requirements (VirtIO RNG, Secure Boot), and secrets handling - proxmox/README.md: add repo-context note pointing back to root README Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01XRzqNDrbnYR22ZgZj1Bg3s --- CLAUDE.md | 48 +++++++++++++++++++++++++++++++++ README.md | 46 ++++++++++++++++++++++++++++++++ pihole/README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++ proxmox/README.md | 2 ++ 4 files changed, 163 insertions(+) create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 pihole/README.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d56e787 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,48 @@ +# CLAUDE.md + +Guidance for Claude Code working in this repo. These instructions +OVERRIDE any default behaviour and must be followed exactly. + +## Repo purpose + +Configuration toolsets and docs for Wayne's Debian-based LAN machines. +Two sections currently exist: `proxmox/` (Proxmox VE hosts) and +`pihole/` (Pi-hole DNS/DHCP). Each has its own README. + +## Safety rules (apply everywhere in this repo) + +- **Never commit secrets.** SSH private keys, passwords, hashes, TOTP + seeds, API tokens, or wifi passphrases must not appear in committed + files. The CI pipeline (`scripts/check-secrets.sh`) enforces this on + every push; the pre-commit hook (`scripts/install-hooks.sh`) catches + it locally before it reaches the remote. +- **`pihole/pull-config.sh` auto-sanitises** sensitive fields from + `pihole.toml` on every pull. If you write config to `pihole/config/` + by any other means, run `pihole/sanitize-config.sh` on the result + before committing. +- **Scripts that SSH into live machines make real changes.** Don't run + `pihole/apply-config.sh` against a production Pi-hole, or any script + in `proxmox/scripts/` against `pve1`, without an explicit same-session + go-ahead from the operator. The section-specific CLAUDE.md files + spell out the per-host guardrails in detail. + +## Section-specific guidance + +- **Proxmox:** see `proxmox/CLAUDE.md` — covers `pve1` (production, + off-limits by default) vs. `pve-test` (sandbox, Claude's default + target), per-host authorisation scope, and network-surgery hazards. +- **Pi-hole:** `pihole/` has no live-host guardrails beyond the secret + rules above. `apply-config.sh` is the only script that touches a live + host; treat its `` argument as production unless you're + explicitly testing on a throwaway instance. + +## Adding a new machine type + +Create a new top-level directory (e.g. `nginx/`, `wireguard/`) with: +- `README.md` — purpose, quick-start, and current status +- `CLAUDE.md` — host-specific guardrails (which hosts are production, + what requires explicit authorisation, what must never be committed) +- `scripts/` and/or `config/` as needed + +Update the root `README.md` layout table and this file's +"Section-specific guidance" list when you do. diff --git a/README.md b/README.md new file mode 100644 index 0000000..0a85ba3 --- /dev/null +++ b/README.md @@ -0,0 +1,46 @@ +# debian-configuration + +Configuration, hardening toolsets, and operational docs for Wayne's +Debian-based LAN machines. Each subdirectory covers a different host or +service type. + +## Layout + +``` +proxmox/ Proxmox VE hosts (pve1 production, pve-test sandbox) +pihole/ Pi-hole DNS/DHCP (config snapshots, pull/apply scripts) +scripts/ Repo-wide scripts (secret scanning, git hook installer) +``` + +## Sections + +### `proxmox/` + +Base configuration and hardening toolset for Proxmox VE hosts. See +`proxmox/README.md` for goals, quick-start, and current status. + +### `pihole/` + +Pi-hole v6 configuration management. Stores a sanitised snapshot of the +live config and provides scripts to pull from or push to a running +instance. See `pihole/README.md` for usage. + +## Secret scanning + +All commits are scanned for secrets by a CI pipeline that runs on both +GitHub Actions and Gitea Actions. The same scan can be run locally: + +```bash +# One-time setup — installs a pre-commit git hook +bash scripts/install-hooks.sh + +# Manual run against the full git history +bash scripts/check-secrets.sh + +# Requires gitleaks on PATH; falls back to Docker if available +# https://github.com/gitleaks/gitleaks#installing +``` + +`pihole/pull-config.sh` automatically redacts sensitive fields +(`pwhash`, `totp_secret`, `app_pwhash`) from `pihole.toml` before +writing it to disk, so the repo stays clean by default. diff --git a/pihole/README.md b/pihole/README.md new file mode 100644 index 0000000..2f41c6e --- /dev/null +++ b/pihole/README.md @@ -0,0 +1,67 @@ +# pihole + +Pi-hole v6 configuration management for `pihole.sweet.home`. + +## What's here + +``` +config/ + pihole.toml Pi-hole v6 main config (sanitised snapshot) + dnsmasq.d/ + 99-ipxe-chainload.conf Custom DHCP rules for EFI/BIOS iPXE PXE boot +pull-config.sh Pull live config from a Pi-hole to a local dir +apply-config.sh Apply a local config dir to a Pi-hole instance +sanitize-config.sh Redact sensitive fields from pihole.toml in-place +``` + +## Usage + +### Snapshot the live config + +```bash +# Pulls pihole.toml + custom dnsmasq.d/ drop-ins, auto-redacts sensitive fields +./pull-config.sh root@pihole ./config +``` + +### Apply config to a new Pi-hole + +```bash +# Destination must have Pi-hole v6 already installed +./apply-config.sh ./config root@pihole-new +``` + +Both scripts take ` ` as positional arguments. +Source/destination is an SSH target (e.g. `root@pihole`, `root@192.168.2.253`) +for the live side and a local directory path for the config side. + +### Restore blocklists after applying + +`apply-config.sh` transfers config only — not the gravity database. +Run this on the destination after applying to rebuild blocklists: + +```bash +ssh root@pihole-new "pihole updateGravity" +``` + +## Notable config + +### `dnsmasq.d/99-ipxe-chainload.conf` + +Enables architecture-aware PXE boot via DHCP: + +| Client | Vendor class | Boot file served | +|---|---|---| +| EFI iPXE already running | arch 7 + option 175 | `http://.../boot.ipxe` | +| BIOS iPXE already running | arch 0 + option 175 | `http://.../boot.ipxe` | +| EFI, no iPXE yet | `PXEClient:Arch:00007` | `ipxe.efi` via TFTP | +| BIOS/legacy, no iPXE yet | `PXEClient:Arch:00000` | `undionly.kpxe` via TFTP | + +Proxmox EFI VMs also require a **VirtIO RNG device** (gives OVMF +enough entropy to complete PXE negotiation) and **Secure Boot disabled** +(`pre-enrolled-keys=0` on the EFI disk, or disabled in UEFI setup). + +## Secrets + +`pihole.toml` is stored with `pwhash`, `totp_secret`, and `app_pwhash` +redacted to empty strings. `pull-config.sh` does this automatically. +To redact manually: `./sanitize-config.sh config/pihole.toml`. diff --git a/proxmox/README.md b/proxmox/README.md index 79bc503..5dfee7f 100644 --- a/proxmox/README.md +++ b/proxmox/README.md @@ -1,3 +1,5 @@ +> Part of the [debian-configuration](../README.md) repo — see the root README for repo-wide layout and secret-scanning setup. + # Proxmox Configuration Base configuration and hardening toolset for Proxmox VE hosts, plus planning