diff --git a/tech_docs/ddi_complete_debian.md b/tech_docs/ddi_complete_debian.md index 223449b..28f6f23 100644 --- a/tech_docs/ddi_complete_debian.md +++ b/tech_docs/ddi_complete_debian.md @@ -1,3 +1,165 @@ +────────────────────────────── +MyCorp “One-Box Wonder” – End-to-End Deployment Guide +────────────────────────────── +A **single Debian 12 server** becomes your DNS, DHCP, CA, and internal PKI authority. +The whole thing is **version-controlled copy-paste playbooks**—no tribal knowledge. + +| Commit | 2024-06-XX | +| Author | you@… | +| Tag | v1.0-symmetry | + +────────────────────────────── +0. TL;DR (30-second cheat-sheet) +```bash +git clone https://git.mycorp.net/infra/onebox-wonder +cd onebox-wonder && ./deploy.sh # walk away, coffee +``` +Everything else below is **reference only**. + +────────────────────────────── +1. Concepts & Naming Convention (never change) +| Element | Value / Pattern | +|-------------------|-----------------| +| Root domain | `mycorp.net` | +| Zone template | `.mycorp.net` | +| Subnet template | `10.0..0/24` (or /28 for infra) | +| Split ranges | `.1–.126` static, `.129–.254` DHCP pool, `.127` broadcast | +| PTR mirror | `.0.10.in-addr.arpa` | +| Hostname pattern | `-..mycorp.net` | + +────────────────────────────── +2. Repository Layout (single Git repo) +``` +onebox-wonder/ +├── README.md +├── deploy.sh # idempotent; runs on fresh Debian 12 +├── inventory/ # optional Ansible inventory +├── files/ +│ ├── dnsmasq.d/ +│ │ ├── 00-global.conf +│ │ ├── 10-lan.conf +│ │ ├── 20-dmz.conf +│ │ └── 99-static-maps.conf +│ ├── dnsmasq-static-hosts +│ ├── step-ca.service +│ └── acme-dns01.sh +├── scripts/ +│ ├── gen-ptr.py # auto-creates reverse records +│ └── check-symmetry.py # lint before commit +└── docs/ + └── CHANGELOG.md +``` + +────────────────────────────── +3. Hardware & VM Assumptions +| Resource | Minimum | Notes | +|----------|---------|-------| +| CPU | 1 vCPU | dnsmasq idle 99 % | +| RAM | 512 MB | 1 MB per 1000 leases | +| Disk | 8 GB | logs rotate weekly | +| NICs | 1 + VLAN sub-interfaces | or 3 physical ports | + +────────────────────────────── +4. Bring-Up Script (deploy.sh – abridged) +```bash +#!/usr/bin/env bash +set -euo pipefail + +HOST_IP=10.0.255.1 +DEBIAN_FRONTEND=noninteractive + +# 4.1 Base OS +apt update && apt -y upgrade +apt -y install dnsmasq curl wget git +systemctl disable --now systemd-resolved +ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf + +# 4.2 Install step-ca & acme.sh +curl -sSL https://dl.smallstep.com/cli/docs-ca-install/latest/step-ca_amd64.deb -o step.deb +dpkg -i step.deb && rm step.deb +curl -sSL https://get.acme.sh | sh -s email=admin@mycorp.net + +# 4.3 Drop configs +rsync -a files/dnsmasq.d/ /etc/dnsmasq.d/ +rsync -a files/dnsmasq-static-hosts /etc/ +rsync -a files/step-ca.service /etc/systemd/system/ +systemctl daemon-reload && systemctl enable --now step-ca + +# 4.4 ACME hook + first cert +install -m 755 files/acme-dns01.sh /usr/local/bin/ +~/.acme.sh/acme.sh --register-account --server https://$HOST_IP/acme/acme/directory +~/.acme.sh/acme.sh --issue -d ns.infra.mycorp.net --dns dns_aliases --dnssleep 3 + +# 4.5 Validation +dnsmasq --test && systemctl restart dnsmasq +dig +short ns.infra.mycorp.net @127.0.0.1 | grep -q "^10.0.255.1$" +echo "✅ One-Box Wonder is live" +``` + +────────────────────────────── +5. Per-Zone Configuration Templates +Copy `10-lan.conf`, rename to new VLAN, sed-replace: + +```ini +# 10-lan.conf +domain=lan.mycorp.net,10.0.0.0/24 +dhcp-range=set:lan,10.0.0.129,10.0.0.254,255.255.255.0,24h +dhcp-option=tag:lan,3,10.0.0.1 +dhcp-option=tag:lan,6,10.0.255.1 +ptr-record=0.0.10.in-addr.arpa,lan.mycorp.net +``` + +────────────────────────────── +6. Static Hosts & PTR Automation +Run `./scripts/gen-ptr.py` before every commit. +Example output appended to `dnsmasq-static-hosts`: + +``` +10.0.20.10 printer-01.lan.mycorp.net +ptr-record=10.20.0.10.in-addr.arpa,printer-01.lan.mycorp.net +``` + +────────────────────────────── +7. Day-2 Operations +| Task | Command | +|------|---------| +| Add subnet | `cp 10-lan.conf 40-cameras.conf && sed -i 's/0/40/g' 40-cameras.conf && git commit -am "add camera vlan"` | +| Re-issue cert | `acme.sh --renew -d host.zone.mycorp.net` | +| Hot backup | nightly `rsync -a /etc/dnsmasq* /var/backups/` | +| Validate symmetry | `./scripts/check-symmetry.py` (CI job) | + +────────────────────────────── +8. Migration Escape Hatches +| Trigger | Plan | +|---------|------| +| > 500 leases /24 | Split into second dnsmasq or migrate DHCP to KEA (keeps DNS) | +| Need DNSSEC views | Insert Unbound in front of dnsmasq, forward internal zones | +| Multi-site | Git push → Ansible pull on second site; subnets remain identical | + +────────────────────────────── +9. Single-Page Runbook (laminate & tape to rack) +``` +Need a new VLAN? +1. echo "VLAN=50 NAME=lab" >> inventory/vlans.csv +2. ./scripts/generate-zone.sh 50 lab +3. git commit -am "VLAN 50 lab" +4. ./deploy.sh +``` + +────────────────────────────── +10. Final Commit Message +``` +feat: v1.0 – symmetry-first DNS/DHCP/CA stack +- single dnsmasq instance, 4 conf files, 1 static hosts file +- integrated step-ca + acme.sh for internal TLS +- repo contains all automations, zero external state +``` + +Done. +Clone, `./deploy.sh`, go back to real work. + +--- + Symmetry-first, engineer-grade DNS + DHCP design (Everything lives on one Debian box running dnsmasq; the numbers look *clean*.)