diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 30fb393..1cfd2d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,6 +67,30 @@ Links to nodes that host or depend on this. ## Changelog ``` +### Plan (`plans/YYYY-MM-DD-slug.md`) + +```markdown +# YYYY-MM-DD — + +## Goal +What this change achieves and why. + +## Current topology / state +Diagram or description of what exists now. + +## Target topology / state +What it looks like after. + +## Pre-flight checklist + +## Step-by-step procedure + +## Verification + +## Post-migration +Changelog entries to write, index status to update. +``` + ### Investigation (`investigations/YYYY-MM-DD-slug.md`) ```markdown @@ -89,6 +113,7 @@ Links to nodes that host or depend on this. - Every container page links to every cross-cutting page it participates in. - Every cross-cutting page lists the nodes that participate. - Every investigation links to the nodes it implicates *and* gets back-linked from each node's changelog. +- Every plan links to the infrastructure pages it affects. When done, update the plan's status in `plans/index.md` and write changelog entries on affected node pages. ## Changelog hygiene diff --git a/infrastructure/network.md b/infrastructure/network.md new file mode 100644 index 0000000..f94fbff --- /dev/null +++ b/infrastructure/network.md @@ -0,0 +1,71 @@ +# Network + +Physical and logical network topology for the homelab. + +## Why + +The homelab runs on a dedicated subnet (`192.168.8.0/24`) isolated from the main household LAN (`192.168.178.0/24`). Isolation is enforced at the Fritz!Box level: homelab devices can reach the internet and main LAN can reach homelab services via explicit port forwards, but main LAN cannot initiate arbitrary connections into the homelab subnet. + +## Hardware + +| Device | Role | +|---|---| +| Fritz!Box 7590 | Main router / ISP gateway, VLAN router between subnets | +| SODOLA 5-Port 2.5Gbit Managed | Homelab switch, all ports in VLAN 10 | + +## VLANs + +| VLAN | Subnet | Gateway | Devices | +|---|---|---|---| +| 1 (native) | 192.168.178.0/24 | 192.168.178.1 | Household LAN — laptops, phones, APs | +| 10 | 192.168.8.0/24 | 192.168.8.1 | Homelab — Proxmox, all LXCs/VMs | + +## Topology + +``` +ISP + └── Fritz!Box 7590 + ├── VLAN 1 192.168.178.0/24 (main LAN) + └── VLAN 10 192.168.8.0/24 (homelab) + │ + └── SODOLA 5-Port 2.5Gbit + ├── Port 1 uplink → Fritz!Box + ├── Port 2 hubris (Proxmox, 192.168.8.77) + ├── Port 3 [device] + ├── Port 4 [device] + └── Port 5 spare +``` + +## DHCP + +Fritz!Box serves DHCP for both VLANs. For VLAN 10 homelab: +- Range: `192.168.8.100 – 192.168.8.240` +- DNS: `192.168.8.2` (Technitium on [CT 107](../containers/107-dns.md)) + +Most homelab hosts use static IPs below `.100` — DHCP only assigns to new/transient devices. + +## DNS + +Split-horizon DNS for `*.hubris.network` served by Technitium on [CT 107](../containers/107-dns.md) at `192.168.8.2:53`. See [dns.md](dns.md) for full detail. + +## Port forwarding + +All inbound port forwards are on the Fritz!Box directly. The old double-hop (Fritz!Box → Slate AX → homelab) was eliminated when the Slate AX was retired. Target IPs are homelab addresses (`192.168.8.x`). + +## Remote access + +- **NetBird mesh** — primary path for remote administration. Authenticated via [Authentik on the VPS](../vps/). +- **Tailscale** — legacy, being phased out. See [mesh.md](mesh.md). + +## Related + +- [DNS](dns.md) — split-horizon config and entry list +- [Ingress](ingress.md) — public entry points via VPS traefik +- [Mesh](mesh.md) — NetBird / Tailscale VPN overlay +- [hosts/hubris.md](../hosts/hubris.md) — Proxmox host +- [CT 107 — dns](../containers/107-dns.md) — Technitium DNS server + +## Changelog + +### 2026-06-01 — Slate AX retired; SODOLA switch added; Fritz!Box becomes homelab gateway +Replaced the GL.iNet Slate AX sub-router with the SODOLA 5-Port 2.5Gbit managed switch. Fritz!Box 7590 now routes VLAN 10 (`192.168.8.0/24`) directly — no more double-NAT. Gateway `192.168.8.1` is unchanged so no LXC or VM needed reconfiguration. Fritz!Box DHCP for VLAN 10 now hands out `192.168.8.2` (Technitium) as DNS, resolving the outstanding "update router DHCP DNS" item. See [migration plan](../plans/2026-06-01-slate-ax-to-sodola-migration.md). diff --git a/plans/2026-06-01-slate-ax-to-sodola-migration.md b/plans/2026-06-01-slate-ax-to-sodola-migration.md new file mode 100644 index 0000000..90b8c83 --- /dev/null +++ b/plans/2026-06-01-slate-ax-to-sodola-migration.md @@ -0,0 +1,131 @@ +# 2026-06-01 — Slate AX → SODOLA Migration + +**Status:** Planned +**Hardware:** SODOLA 5-Port 2.5Gbit Managed Switch replacing GL.iNet Slate AX +**Router:** Fritz!Box 7590 + +## Goal + +Remove the Slate AX sub-router. It adds double-NAT, double port-forward complexity, and a second DHCP/gateway hop. Replace with the SODOLA switch so Proxmox and homelab devices attach directly to the Fritz!Box—without changing any of their IPs. + +## Current topology + +``` +ISP + └── Fritz!Box 7590 (192.168.178.1) + └── GL.iNet Slate AX WAN: 192.168.178.x LAN: 192.168.8.1 [NAT] + ├── hubris (Proxmox) 192.168.8.77 + ├── + all 16 LXCs on vmbr0 bridged to the same subnet + └── other homelab devices +``` + +## Target topology + +``` +ISP + └── Fritz!Box 7590 + ├── VLAN 1 192.168.178.0/24 (main LAN — laptops, phones) + └── VLAN 10 192.168.8.0/24 gateway 192.168.8.1 (homelab, no NAT) + │ + └── SODOLA 5-Port 2.5Gbit + ├── Port 1 uplink → Fritz!Box LAN port + ├── Port 2 hubris (Proxmox) 192.168.8.77 + ├── Port 3 [homelab device] + ├── Port 4 [homelab device] + └── Port 5 spare +``` + +Fritz!Box takes over `192.168.8.1` — the same gateway IP the Slate AX used. No static IPs or gateway entries change on any LXC or VM. + +See [network architecture](../infrastructure/network.md) for the permanent topology reference. + +## Pre-flight checklist + +- [ ] Note Slate AX gateway IP on the homelab subnet (expected `192.168.8.1`) +- [ ] Note Slate AX upstream DNS setting (what it forwards to) +- [ ] List all port forwards currently on the Slate AX → move these to Fritz!Box +- [ ] List all port forwards on Fritz!Box that point at the Slate AX WAN IP → collapse these into direct homelab-IP rules +- [ ] Confirm Fritz!OS version supports "second IP network" (Fritz!OS 7.x required) +- [ ] SSH into hubris: verify `grep gateway /etc/network/interfaces` → `192.168.8.1` +- [ ] SODOLA web UI accessible and ports configurable before physical move + +## Fritz!Box configuration + +**Path:** Home Network → Network → Network Settings → IPv4 Addresses → Add IP network + +| Field | Value | +|---|---| +| IP address | `192.168.8.1` | +| Subnet mask | `255.255.255.0` | +| DHCP range | `192.168.8.100 – 192.168.8.240` | +| Assign to | LAN port that connects to SODOLA | +| Network isolation | Enabled (blocks main LAN from initiating into homelab) | +| DNS for DHCP clients | `192.168.8.2` (Technitium on [CT 107](../containers/107-dns.md)) | + +After creating the network, move any port forwards from the Slate AX into Fritz!Box → Internet → Permits (target IPs are now directly reachable on `192.168.8.x`). + +## SODOLA configuration + +All ports in VLAN 10, untagged (simple access-port setup): + +| Port | PVID | Role | +|---|---|---| +| 1 | 10 | Uplink → Fritz!Box | +| 2 | 10 | hubris (Proxmox) | +| 3 | 10 | homelab device | +| 4 | 10 | homelab device | +| 5 | 10 | spare | + +## Proxmox / LXC changes + +If the Slate AX gateway was `192.168.8.1`: **no changes needed**. Fritz!Box takes the same IP. + +If Slate AX used a different gateway (e.g. `.254`), update: +```bash +# on hubris +nano /etc/network/interfaces # change gateway line +ifreload -a +# for each LXC with a static gateway +pct config <id> # check net0: line for gw= +pct set <id> --net0 name=eth0,bridge=vmbr0,ip=<ip>/24,gw=192.168.8.1 +``` + +## DNS after migration + +Technitium ([CT 107](../containers/107-dns.md)) at `192.168.8.2` continues to serve split-horizon DNS for `hubris.network`. The Fritz!Box DHCP server for VLAN 10 hands out `192.168.8.2` as the DNS server. This fixes the "update router DHCP DNS from dead .180 → .2" outstanding item in [dns.md](../infrastructure/dns.md). + +## Cutover procedure + +1. Configure Fritz!Box second IP network (VLAN 10 / `192.168.8.1`) — verify DHCP works via a test laptop on the target port. +2. Configure SODOLA port VLAN assignments. +3. Connect SODOLA port 1 → Fritz!Box target LAN port. +4. Move hubris ethernet → SODOLA port 2. Proxmox should stay reachable immediately (same gateway IP). +5. Move remaining homelab devices to SODOLA ports 3–5. +6. Decommission Slate AX. + +## Verification + +```bash +# internet from Proxmox +ssh proxmox "ping -c3 1.1.1.1" + +# Fritz!Box main LAN reachable (routing between VLANs works) +ssh proxmox "ping -c3 192.168.178.1" + +# split-horizon DNS via Technitium still resolves +ssh proxmox "dig @192.168.8.2 +short git.hubris.network" +# expected: 192.168.8.175 + +# Caddy reverse proxy responds +curl -sk https://git.hubris.network | head -5 + +# Authentik on VPS still reachable +curl -sk https://auth.hubris.network/if/flow/default-authentication-flow/ | head -5 +``` + +## Post-migration + +- Update [network.md](../infrastructure/network.md) topology to reflect new state. +- Add changelog entries to [hosts/hubris.md](../hosts/hubris.md) and any affected container pages. +- Update status in [plans/index.md](index.md) to `Done`. +- If anything went sideways, open an investigation in `investigations/`. diff --git a/plans/index.md b/plans/index.md new file mode 100644 index 0000000..6268434 --- /dev/null +++ b/plans/index.md @@ -0,0 +1,16 @@ +# Plans + +Pre-flight runbooks for planned changes that haven't happened yet. Once executed, move the outcome to `investigations/` (if anything interesting happened) or just a changelog entry on the affected node pages. + +## Index + +| Date | Title | Status | +| ---- | ----- | ------ | +| 2026-06-01 | [Slate AX → SODOLA managed switch migration](2026-06-01-slate-ax-to-sodola-migration.md) | Planned | + +## Conventions + +- File name: `YYYY-MM-DD-<slug>.md`. Use the *target* date if known, otherwise the planning date. +- Status: `Planned` → `In Progress` → `Done` (update index entry as it moves). +- When done: add a changelog entry on every affected node page, then update status to `Done` here. If things went sideways, open an investigation. +- Plans are append-only once execution starts — don't rewrite pre-flight intent after the fact.