TopherMayor/hermes-ice
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: homelab infrastructure wiki

Browse Source 
- Full Obsidian vault content
- Host configs (ice, grizzley, ubuntu, proxmox, truenas, panda, hyte)
- Media stack documentation
- Traefik HA setup
- Automation scripts
- Bachelor party planning
This commit is contained in:
Hermes Agent
2026-05-24 16:08:40 -07:00
parent d132442429
commit e4d91aadf9
285 changed files with 30018 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
homelab/docs/ai-applications.md Normal file
View File

@@ -0,0 +1,44 @@
---
project:
name: AI Applications
status: active
category: application
source: live-verification
created: 2026-04-19
updated: 2026-04-19
description: AI application services running on ubuntu including job pipeline, alert aggregation, and media intelligence
tags: [ai, applications, infrastructure]
---
# AI Application Services
AI-powered application services running on ubuntu (192.168.50.61).
## Services
| Service | Status | Purpose |
|---------|--------|---------|
| **AI Job Pipeline** | Backend restarting | AI-driven job orchestration (frontend + backend + postgres) |
| **AI Alert Aggregator** | Backend restarting | AI-powered alert aggregation (frontend + backend + postgres) |
| **AI Media Intelligence** | Backend restarting | AI media analysis and intelligence |
| **AI Subscriptions** | Healthy | AI subscription management |
| **Homelab Inventory** | Backend restarting | Automated infrastructure inventory |
## Other Application Services
| Service | Purpose | Status |
|---------|---------|--------|
| **Docker Registry** | Private container image registry | Running |
| **Docker OSX** | macOS VM in Docker for testing | Running |
| **Faster Whisper Server** | Local speech-to-text (CUDA) | Healthy |
## Notes
- Several AI application backends are in a restart loop — may need investigation
- All services are Docker containers on ubuntu
- Docker Registry provides private image hosting at `registry:5000`
## Related
- [[../architecture.md|Homelab Architecture]]
- [[../../homelab/raw/articles/ai-assistant/project.md|AI Assistant Configuration]]

73
homelab/docs/grizzley-services.md Normal file
View File

@@ -0,0 +1,73 @@
---
project:
name: Grizzley Infrastructure Services
status: active
category: infrastructure
source: live-verification
created: 2026-04-19
updated: 2026-04-19
description: Services running on grizzley (Raspberry Pi 5) including Komodo, Hermes, Vaultwarden, and Minecraft
tags: [infrastructure, grizzley, komodo, hermes, minecraft]
---
# Grizzley Services
All services running on grizzley (192.168.50.84, Raspberry Pi 5, Ubuntu 25.10).
## Infrastructure
| Service | Image | Status | Purpose |
|---------|-------|--------|---------|
| **Traefik** (traefik-pi) | traefik:v3.6.7 | Healthy | Edge ingress, primary ACME certificate source |
| **Homepage** | homepage-grizzley | Healthy | Startpage dashboard |
| **Komodo** | komodo | Healthy | Docker Compose stack management (core) |
| **Komodo MongoDB** | komodo-mongo | Healthy | Komodo database |
## AI & Management
| Service | Image | Status | Purpose |
|---------|-------|--------|---------|
| **aiomanager** | aiomanager | Healthy | AI operations manager |
| **aiomanager_db** | aiomanager_db | Healthy | AI manager database |
## Migrated Services
These services were migrated from ubuntu to grizzley:
| Service | Purpose | Notes |
|---------|---------|-------|
| **Vaultwarden** | Password manager | DB via remote postgres-shared on ubuntu |
| **Uptime Kuma** | Uptime monitoring | Self-contained SQLite |
## Gaming
| Service | Port | Purpose |
|---------|------|---------|
| **Minecraft Bedrock (standby)** | UDP/19132 | Primary Minecraft Bedrock server |
| **Minecraft Bedrock (sison)** | UDP/19134 | Secondary Minecraft Bedrock server |
## Hermes Agent
Systemd service (`hermes-gateway.service`) providing:
- Telegram bot integration for alerts and management
- Webhook on port 8644 for Prometheus Alertmanager
- SSH-based homelab monitoring
- 3 cron jobs: Health Check (15m), Container Monitor (30m), Maintenance (6h)
## Komodo Stack Management
Komodo manages Docker Compose stacks on both ubuntu and grizzley:
- Mode: `files_on_host` — runs `docker compose` in existing host directories
- 19 stacks registered (14 ubuntu, 5 grizzley)
- Periphery agent runs on each host, connects to Komodo Core on grizzley
## Network
- External network: `traefik-proxy` for Traefik-routed services
- Internal network: `komodo-internal` for MongoDB isolation
- NFS-mounted certs from TrueNAS: `/mnt/truenas/traefik-certs/grizzley`
## Related
- [[../architecture.md|Homelab Architecture]]
- [[../project.md|Homelab Project]]

51
homelab/docs/ice-host.md Normal file
View File

@@ -0,0 +1,51 @@
---
project:
name: Ice Host
status: active
category: infrastructure
source: live-verification
created: 2026-04-19
updated: 2026-04-19
description: Ice control plane host (Raspberry Pi 4) running OpenCode and utility services
tags: [infrastructure, ice, control-plane, opencode]
---
# Ice Host (192.168.50.197)
Control plane node running on Raspberry Pi 4 with Ubuntu 25.10 (aarch64).
## Services
### Systemd Services
| Service | Status | Port | Purpose |
|---------|--------|------|---------|
| `opencode-web.service` | Active/Enabled | 4096 | OpenCode web interface |
| `docker.service` | Active | - | Docker Engine |
### Docker Containers
| Container | Image | Status | Purpose |
|-----------|-------|--------|---------|
| camofox | camofox:aarch64 | Up 3 days | Camofox utility service |
### Not Running
- **Nanobot** — Previously planned AI agent, never deployed
- **App Factory** — Config exists in `homelab/ice/` but not currently running
## Configuration
- OpenCode config: `homelab/ice/opencode.json`
- App Factory: `homelab/ice/` (memoir.json, oh-my-opencode.json, systemd/)
## Key Facts
- No Docker socket available for Komodo Periphery
- OpenCode runs via systemd (not Docker)
- Minimal host — focused on OpenCode and lightweight services
## Related
- [[../architecture.md|Homelab Architecture]]
- [[opencode-cluster.md|OpenCode Cluster]]

61
homelab/docs/media-extensions.md Normal file
View File

@@ -0,0 +1,61 @@
---
project:
name: Media Extensions
status: active
category: infrastructure
source: live-verification
created: 2026-04-19
updated: 2026-04-19
description: Expanded media stack including music, ebooks, audiobooks, manga, and media quality management
tags: [infrastructure, media, music, ebooks, audiobooks]
---
# Media Extensions
Beyond the core media stack (Radarr, Sonarr, Jellyfin), the homelab runs extended media services for music, ebooks, audiobooks, and quality management.
## Music Services
| Service | Image | Purpose | Status |
|---------|-------|---------|--------|
| **Navidrome** | deluan/navidrome | Music streaming server | Unhealthy |
| **Lidarr** | linuxserver/lidarr | Music automation (arr) | Unhealthy |
| **Musicseerr** | localhost:5000/musicseerr | Music request system | Healthy |
## Ebook & Reading Services
| Service | Image | Purpose | Status |
|---------|-------|---------|--------|
| **Calibre** | linuxserver/calibre | Ebook library management | Running |
| **Calibre-Web** | linuxserver/calibre-web | Web ebook reader | Healthy |
| **Kavita** | jvmilazz0/kavita | Manga/comic reader | Healthy |
| **LazyLibrarian** | linuxserver/lazylibrarian | Book automation (arr) | Healthy |
## Audiobook Services
| Service | Image | Purpose | Status |
|---------|-------|---------|--------|
| **Audiobookshelf** | advplyr/audiobookshelf | Audiobook/podcast server | Unhealthy |
## Media Management
| Service | Image | Purpose | Status |
|---------|-------|---------|--------|
| **RecCollection** | docker-local-backend | Media collection manager | Healthy |
| **Unified Media Manager** | unified-media-manager | Unified media management | Healthy |
| **Stremio Server** | stremio/server | Media streaming | Healthy |
| **NZBdav** | nzbdav/nzbdav | Usenet WebDAV access | Running |
## Media Quality Assurance
| Service | Image | Purpose |
|---------|-------|---------|
| **Recyclarr** | recyclarr/recyclarr | Radarr/Sonarr quality profile management |
| **Analyzarr** | media-qa-analyzarr | Media file quality analysis |
All media services run on **ubuntu** (192.168.50.61). Media files are stored on TrueNAS NFS at `/mnt/truenas/mediadata/`.
## Related
- [[../architecture.md|Homelab Architecture]]
- [[../project.md|Homelab Project]]

61
homelab/docs/opencode-cluster.md Normal file
View File

@@ -0,0 +1,61 @@
---
project:
name: OpenCode Cluster
status: active
category: infrastructure
source: live-verification
created: 2026-04-19
updated: 2026-04-19
description: OpenCode AI coding assistant cluster deployment across homelab hosts
tags: [infrastructure, opencode, ai, cluster]
---
# OpenCode Cluster Deployment
OpenCode AI coding assistant deployed as systemd services across the homelab cluster.
## Instances
| Instance | Host | Port | Traefik Route | Status |
|----------|------|------|---------------|--------|
| ubuntu | 192.168.50.61 | 4096 | opencode.tophermayor.com | Active/Enabled |
| ice | 192.168.50.197 | 4096 | opencode-ice.tophermayor.com | Active/Enabled |
| grizzley | 192.168.50.84 | 4096 | — | Inactive/Disabled |
## Service Management
All instances run as `opencode-web.service` via systemd:
```bash
# Check status
systemctl status opencode-web
# Restart
sudo systemctl restart opencode-web
# View logs
journalctl -u opencode-web -f
```
## Shared Infrastructure
- **Qdrant** (192.168.50.61:6333) — Shared vector memory backend
- **Ollama** (192.168.50.61:11434) — Local embedding generation
## Configuration
Per-host config files in `homelab/<host>/opencode/`:
- `opencode.json` — Main OpenCode configuration
- `oh-my-opencode.json` — Framework configuration
## Traefik Routing
OpenCode instances use dedicated Traefik middlewares:
- `local-only@file` — IP whitelist
- `opencode-streaming@file` — SSE support
- `opencode-cors@file` — CORS headers
## Related
- [[../architecture.md|Homelab Architecture]]
- [[../../homelab/raw/articles/ai-assistant/project.md|AI Assistant Configuration]]

52
homelab/docs/runbooks/oh-my-opencode-setup.md Normal file
View File

@@ -0,0 +1,52 @@
# oh-my-opencode Setup & Troubleshooting Runbook
## Overview
This runbook covers the steps required to enable `oh-my-opencode` properly, ensuring all primary agents (Sisyphus, Atlas, Prometheus) load and function correctly across the homelab infrastructure.
## Problem Context
Initially, `oh-my-opencode` was installed but failed to load primary agents. Symptoms included missing agents in the TUI and logs showing plugins loading except for `oh-my-opencode`.
## Root Causes Identified
1. **Malformed Configuration**: `oh-my-opencode.json` had broken JSON syntax and missing agent/hook blocks.
2. **Plugin Loading Order**: `oh-my-opencode` was not the first plugin in `opencode.json`, potentially causing initialization delays or conflicts.
3. **Missing Built-in Definitions**: Primary agents were not explicitly defined with correct model/category mappings.
## Step-by-Step Enablement
### 1. Update `opencode.json`
Ensure `oh-my-opencode@latest` is the first plugin in the list. This ensures it initializes before other plugins that might depend on it or conflict with its hooks.
```json
"plugin": [
"oh-my-opencode@latest",
"opencode-antigravity-auth@latest",
"./plugin/kilocode/plugin_kilocode.ts"
]
```
### 2. Standardize `oh-my-opencode.json`
Apply the standardized configuration with all hooks enabled and primary agents defined. Key sections to include:
- `sisyphus_agent`: Enable planner and plan replacement.
- `hooks`: Enable all 16+ hooks including `session-recovery`, `rules-injector`, and `think-mode`.
- `agents`: Define `sisyphus`, `atlas`, `prometheus`, `oracle`, `librarian`, and `explore` with appropriate models.
### 3. Verify Plugin Loading
Check OpenCode logs for successful plugin initialization:
```bash
grep "service=plugin.*loading" ~/.local/share/opencode/log/*.log
```
Look for: `service=plugin path=...oh-my-opencode/dist/index.js loading plugin`
### 4. Verify Agents in TUI
Launch OpenCode and verify `Sisyphus` appears in the agent selection. Also test slash commands like `/refactor` or `/git-master`.
## GitOps Workflow
All configuration changes must be made in the `homelabagentroot` repository and pushed to trigger the automated deployment sync.
1. Edit configs in `homelab/configs/opencode-global/`
2. Commit and push to `origin main`
3. The Gitea runner will pull changes and restart services as configured.
---
**Last Updated:** January 25, 2026
**Status:** Verified Working ✅

134
homelab/docs/unifi-execution-plan.md Normal file
View File

@@ -0,0 +1,134 @@
---
project:
name: UniFi Execution Plan
status: active
category: infrastructure
source: homelabagentroot
created: 2026-03-17
updated: 2026-03-17
description: Exact staged UniFi zone and firewall change plan derived from current live state and authoritative host repos
goals:
- Apply the minimum set of high-value zone and policy changes safely
- Preserve application reachability while tightening security boundaries
- Provide an execution sequence that supports rollback and verification
priority: high
tags: [unifi, firewall, zones, execution, planning]
---
# UniFi Execution Plan
## Current Status
Implemented on 2026-03-17:
- `Family of D.` moved from `Management` to `Internal`
- `Management` reduced to `Default` only
- New `Internal` allow rules created for `Servers` (`80/443`), `IoT`, and `Staging`
- Logging enabled on selected user-defined edge and VPN policies
- Staged DHCP reservations enabled for `grizzley`, `ice`, and `homeassistant`
- First host-side migration step completed for `truenas`: default gateway moved from `192.168.1.1` to `192.168.50.1`
- `proxmox` default gateway moved from `192.168.1.1` to `192.168.50.1`
- `ubuntu` default gateway moved from `192.168.1.1` to `192.168.50.1`
- `proxmox` legacy `192.168.1.11` address removed from `vmbr0`
- `ubuntu` legacy `192.168.1.61` address removed from `enp6s18`
- `truenas` legacy `192.168.1.12` address removed from `enp6s17`
- `grizzley` Wi-Fi config removed
- `ice` Wi-Fi config removed
- staging-side `192.168.40.x` addresses removed from `truenas`, `grizzley`, and `ice`
Still pending:
- later interface cleanup for legacy `truenas`, `proxmox`, and `ubuntu` addresses that still remain active
- later interface cleanup for staging-side addresses that still remain active on `truenas`, `grizzley`, and `ice`
- cleanup of stale UniFi controller observations for the removed Ubuntu legacy address
- cleanup of stale or lagging UniFi controller observations for removed Wi-Fi paths on `grizzley` and `ice`
- decide whether remaining infrastructure-side `192.168.30.x` addresses should persist long-term
- deny-rule logging expansion
- public `HTTP` exposure review
- duplicate-rule cleanup and broader rule tightening
- maintenance-window execution of the one-host-at-a-time migration runbook
## Reservation Update Notes
The UniFi controller accepted staged reservation updates for:
- `grizzley` -> `192.168.10.145`
- `ice` Wi-Fi -> `192.168.10.178`
- `ice` wired -> `192.168.50.197`
- `homeassistant` -> `192.168.30.196`
- `ubuntu` -> `192.168.1.61`
- `proxmox` -> `192.168.1.11`
The active `truenas` reservation at `192.168.1.12` remains valid.
Follow-up change:
- the stale secondary TrueNAS fixed-IP reservation at `192.168.1.145` has been cleared; the remaining task is to decide how many live TrueNAS interfaces should persist long-term
- Wi-Fi reservations for `grizzley` and `ice` were cleared after host-side Wi-Fi removal
- Staging access rules were disabled after staging-side host addresses were removed
## Scope
This plan focuses on the first safe wave of changes:
- restore `Management` as an infrastructure-only trust boundary
- keep `Internal` for trusted user devices only
- preserve `Guest` internet-only access
- preserve `IoT` with narrow app exceptions
- maintain `Servers` as the homelab application segment
- treat `Vpn` as explicit least-privilege remote access
## Phase 1: Zone Corrections
1. Remove `Family of D.` from `Management`
2. Ensure `Family of D.` is mapped to `Internal`
3. Keep `Default` in `Management`
4. Keep `Production` in `Servers`
5. Keep `Will of D. IoT` in `IoT`
6. Keep `Will of D. (Guest)` in `Guest`
7. Keep `UGC WireGuard` in `Vpn` unless there is a deliberate reason to merge admin semantics elsewhere
## Phase 2: Logging Improvements
1. Enable logging on edge-facing allow rules:
- `External -> Web Proxy`
- `External -> HTTPS`
- `External -> HTTP` if retained
2. Enable logging on key deny rules:
- `Guest -> Internal`
- `Guest -> Servers`
- `IoT -> Internal`
- `IoT -> Management`
3. Enable logging on sensitive admin rules:
- `Vpn -> Management`
- `Vpn -> Servers`
## Phase 3: Rule Tightening
1. Review and narrow broad `Internal -> Servers` rules to app ports only
2. Review and narrow broad `IoT -> Servers` rules to explicit media and automation ports only
3. Review `Vpn -> Management` and reduce to the smallest needed host/port set
4. Remove duplicate return-path rules once stateful behavior is confirmed
5. Remove or disable `HTTP` exposure if no longer required for redirect or certificate workflows
## Phase 4: Host Placement Follow-Through
1. Normalize infrastructure hosts to their intended addresses where possible
2. Keep split-plane exceptions documented explicitly, such as `panda`
3. Revisit firewall rules after host addressing settles so the final policy set matches reality
## Verification Checklist
- `Management` clients can reach infrastructure admin interfaces
- `Internal` clients can reach approved apps over `HTTPS`
- `Guest` clients have internet access only
- `IoT` clients can reach only approved services such as Jellyfin, Traefik, and Home Assistant where required
- VPN clients retain the minimum access needed for admin work
- Public apps remain reachable through the intended hardened edge
## Rollback Principles
- export before each major edit
- change one zone or rule set at a time
- verify from at least one host in each affected zone
- keep a saved copy of previous zone membership and rule ordering

76
homelab/docs/unifi-final-change-report-2026-03-17.md Normal file
View File

@@ -0,0 +1,76 @@
---
project:
name: UniFi Final Change Report 2026-03-17
status: active
category: infrastructure
source: homelabagentroot
created: 2026-03-17
updated: 2026-03-17
description: Concise before-and-after report for the March 17 UniFi cleanup and host migration wave
goals:
- Capture the final outcome of the cleanup wave
- Summarize what changed, what was verified, and what remains
- Provide a short artifact suitable for handoff or archival
priority: medium
tags: [unifi, report, migration, summary]
---
# UniFi Final Change Report 2026-03-17
## Before
- `Management` included both `Default` and `Family of D.`
- `ubuntu`, `proxmox`, and `truenas` still used legacy `192.168.1.x` paths
- `grizzley` and `ice` still had active Wi-Fi participation on `Family of D.`
- `truenas`, `grizzley`, and `ice` still had staging-side `192.168.40.x` addresses
- staging access policies were still enabled
## After
- `Family of D.` now lives in `Internal`
- `Management` now maps only to `Default`
- legacy `192.168.1.x` removed from:
- `ubuntu`
- `proxmox`
- `truenas`
- Wi-Fi removed from:
- `grizzley`
- `ice`
- staging `192.168.40.x` removed from:
- `truenas`
- `grizzley`
- `ice`
- disabled:
- `Vpn to Staging`
- `Allow Servers to Staging`
## Verified Retained 192.168.30.x Paths
These were intentionally retained because they still expose live service endpoints:
| Host | Retained Address | Verified Ports |
|------|------------------|----------------|
| `ubuntu` | `192.168.30.61` | `80`, `443`, `8096` |
| `proxmox` | `192.168.30.11` | `22`, `8006`, `3128` |
| `grizzley` | `192.168.30.84` | `80`, `443`, `8080` |
| `ice` | `192.168.30.197` | `22`, `4096`, `18791` |
## Controller State Notes
- UniFi no longer shows the removed legacy `192.168.1.61` path for `ubuntu`
- UniFi shows `ice` only on the wired production path
- UniFi still shows one disconnected/no-IP `grizzley` IoT-side record
- A direct delete attempt against that stale `grizzley` client record returned `api.err.NotFound`, so the safest assumption is controller-history lag rather than an active client entry
## Remaining Follow-Up
- Decide service-by-service whether the retained `192.168.30.x` addresses should remain long-term
- Allow the stale disconnected `grizzley` UniFi record to age out, or revisit if it persists
- Review public `HTTP` exposure and duplicate firewall rules in a future maintenance pass
## Related Docs
- [[unifi-post-migration-summary-2026-03-17.md|UniFi Post-Migration Summary 2026-03-17]]
- [[unifi-host-migration-runbook.md|UniFi Host Migration Runbook]]
- [[unifi-execution-plan.md|UniFi Execution Plan]]
- [[unifi-rollback-2026-03-17.md|UniFi Rollback 2026-03-17]]

111
homelab/docs/unifi-host-migration-checklist.md Normal file
View File

@@ -0,0 +1,111 @@
---
project:
name: UniFi Host Migration Checklist
status: planning
category: infrastructure
source: homelabagentroot
created: 2026-03-17
updated: 2026-03-17
description: Host-by-host checklist for aligning live UniFi placement with authoritative host repo intent
goals:
- Normalize infrastructure hosts to intended network zones
- Reduce accidental dual-homing and cross-zone ambiguity
- Preserve app reachability during staged network changes
priority: high
tags: [unifi, migration, hosts, checklist, planning]
---
# UniFi Host Migration Checklist
## Overview
This checklist breaks the UniFi optimization work into host-specific actions. It is written to support staged execution and validation.
## Shared Pre-Checks
- [ ] Export current UniFi networks, zones, and firewall policies
- [ ] Confirm DHCP reservations for all infrastructure hosts
- [ ] Confirm DNS records that point at `ubuntu`, `grizzley`, `ice`, `proxmox`, `truenas`, `panda`, and `traefik-lxc`
- [ ] Confirm out-of-band or fallback admin access for each host before moving network placement
- [ ] Enable logging on critical deny and edge allow rules before major topology changes
## Current Staged-Cutover Status
- [x] `Family of D.` moved from `Management` to `Internal`
- [x] `Management` reduced to `Default` only
- [x] Staged DHCP reservation enabled for `grizzley` Wi-Fi path at `192.168.10.145`
- [x] Staged DHCP reservations enabled for `ice` at `192.168.10.178` and `192.168.50.197`
- [x] Staged DHCP reservation enabled for `homeassistant` app plane at `192.168.30.196`
- [x] `ubuntu` reservation normalized to its current live `Default` network address `192.168.1.61`
- [x] `proxmox` reservation refreshed and validated through UniFi at `192.168.1.11`
- [x] `truenas` primary reservation confirmed at `192.168.1.12`
Follow-up findings:
- `ubuntu` and `proxmox` accepted the legacy fixed-IP update format and now reflect their current live `Default` network addresses correctly in UniFi.
- `truenas` already had a valid primary reservation at `192.168.1.12` plus a second physical-NIC reservation at `192.168.1.145`.
- The `truenas` update conflict came from the second NIC record, not from the active primary reservation itself.
## Ubuntu
Current intent: primary Docker host and public/internal app edge on `192.168.50.61`
- [ ] Confirm whether `ubuntu` should live only on `Production` or stay dual-homed during migration
- [ ] If moving, create or verify reservation for `192.168.50.61`
- [ ] Ensure Traefik, Authentik, Gitea, Vaultwarden, and OpenCode URLs resolve to the correct server-side path
- [ ] Verify inbound `HTTPS` routes after network normalization
- [ ] Remove stale `Default`-side assumptions from firewall rules after validation
## Grizzley
Current intent: edge ingress on `192.168.50.84`
- [ ] Verify whether the current `192.168.10.145` presence is intentional or drift
- [ ] Confirm the desired primary address remains `192.168.50.84`
- [ ] Keep Traefik and admin access in `Servers` and `Management`, not `Internal`
- [ ] Remove any unintended trusted-client or Wi-Fi placement once validated
## Ice
Current intent: control-plane infrastructure on `192.168.50.197`
- [ ] Verify whether `192.168.10.178` is an intentional secondary path
- [ ] Keep control-plane traffic anchored to `Production`
- [ ] Limit any secondary management path to a documented admin-only use case
- [ ] Remove broad `Internal`-side reachability if the extra placement is not required
## Proxmox
Current intent: infrastructure-only hypervisor on `192.168.50.11`
- [ ] Confirm the hypervisor should not remain on `192.168.1.11`
- [ ] Verify management-only access to the hypervisor UI and SSH
- [ ] Confirm `traefik-lxc` (`192.168.50.115`) and other LXC workloads remain server-side only
- [ ] Review whether any user networks directly reach Proxmox today and remove that access if unnecessary
## TrueNAS
Current intent: storage-only host on `192.168.50.12`
- [ ] Confirm whether `192.168.1.12` is a legacy path, active secondary interface, or stale observation
- [ ] Keep storage admin access on `Management` and selected server workflows only
- [ ] Confirm mounts and NFS exports still resolve correctly after address normalization
- [ ] Document the final intended interface model explicitly
## Panda / Home Assistant
Current intent: app endpoint on `192.168.30.196`, SSH/admin endpoint on `192.168.50.196`
- [ ] Preserve the split app/admin model unless there is a strong reason to collapse it
- [ ] Confirm Home Assistant app access remains available from intended `Internal`, `Management`, and selected `IoT` clients
- [ ] Restrict admin SSH path to `Management` and approved VPN clients
- [ ] Keep Home Assistant runtime state out of Git-tracked locations
## Post-Migration Validation
- [ ] Confirm all host DHCP reservations and names resolve correctly
- [ ] Confirm reverse proxy paths for public and internal apps
- [ ] Confirm Home Assistant, Jellyfin, Gitea, Vaultwarden, and Authentik remain reachable from intended zones
- [ ] Confirm guests have internet-only access
- [ ] Confirm IoT devices can reach only their approved service exceptions
- [ ] Confirm VPN access is least-privilege and still sufficient for admin work

153
homelab/docs/unifi-host-migration-runbook.md Normal file
View File

@@ -0,0 +1,153 @@
---
project:
name: UniFi Host Migration Runbook
status: planning
category: infrastructure
source: homelabagentroot
created: 2026-03-17
updated: 2026-03-17
description: One-host-at-a-time runbook for moving infrastructure from 192.168.1.x drift toward documented 192.168.50.x placement
goals:
- Migrate infrastructure hosts without lockout
- Validate services and routing after each host move
- Preserve rollback options at every step
priority: high
tags: [unifi, migration, runbook, infrastructure]
---
# UniFi Host Migration Runbook
## Strategy
Use a staged maintenance-window approach. Move one host at a time, verify service reachability, then continue.
## Pre-Migration Rules
- Keep working SSH access before changing a host address
- Keep DHCP reservation and target network prepared before host cutover
- Verify DNS, reverse proxy, and firewall reachability after each move
- Roll back immediately if the management path or primary app path fails
## Recommended Order
1. `truenas`
2. `proxmox`
3. `ubuntu`
4. `grizzley`
5. `ice`
This order reduces blast radius by moving storage and hypervisor access before the primary public app edge.
## Host Steps
### TrueNAS
Target intent: normalize around `192.168.50.12`
- Confirm which NICs are intentionally active
- Confirm whether `192.168.1.12` remains required during transition
- Confirm NFS/SMB exports remain reachable from `ubuntu` and other consumers
- Remove stale or duplicate UniFi client records only after confirming the active interface map
- Cut over management and storage clients to the server-side address
Rollback:
- Re-enable the previous interface/gateway path
- Restore the old fixed IP if needed
### Proxmox
Target intent: normalize around `192.168.50.11`
- Verify direct shell access before change
- Confirm access to hosted services such as `traefik-lxc` and `adguard`
- Move the management path and validate web UI, SSH, and LXC/VM operations
Rollback:
- Restore previous interface config and reservation
### Ubuntu
Target intent: normalize around `192.168.50.61`
- Verify SSH access and Docker service health before cutover
- Confirm Traefik, Authentik, Gitea, Vaultwarden, OpenCode, Jellyfin, and other critical apps are healthy
- Update reverse proxy assumptions if any services still reference the old `192.168.1.61` path
- Validate external and internal HTTPS after the move
Rollback:
- Restore `192.168.1.61`
- Re-test `gitea.tophermayor.com`, `opencode.tophermayor.com`, and other critical ingress routes
### Grizzley
Target intent: normalize around `192.168.50.84`
- Decide whether the `192.168.10.145` Wi-Fi presence is temporary or required
- Preserve edge ingress management access during any move
### Ice
Target intent: normalize around `192.168.50.197`
- Decide whether the `192.168.10.178` Wi-Fi path is still required
- Preserve OpenCode control-plane access during any move
## Post-Step Validation
- SSH works from management
- DNS resolves correctly
- Reverse proxy paths work where expected
- Firewall logs show expected zone flows only
- No new unexpected east-west traffic appears
## Notes From Current State
- `Family of D.` is now in `Internal`, not `Management`
- `ubuntu` and `proxmox` reservations are aligned to current live `Default` addresses
- `truenas` still has multiple NIC/client records and should be cleaned up carefully before a move
- `grizzley`, `ice`, and `homeassistant` staged reservations are already in place for their current live paths
## Executed Migration State
Executed on 2026-03-17:
- `truenas` secondary stale reservation at `192.168.1.145` was cleared
- `truenas` management and egress preference was shifted to `Production` by changing the host default gateway from `192.168.1.1` to `192.168.50.1`
- `truenas` DNS was normalized to prefer `192.168.50.157` with `1.1.1.1` as secondary
- `proxmox` default route was moved from `192.168.1.1` on `vmbr0` to `192.168.50.1` on `vmbr0.50`, and `/etc/network/interfaces` was updated accordingly
- `ubuntu` default route was moved from `192.168.1.1` on `enp6s18` to `192.168.50.1` on `vlan50`, and `/etc/netplan/50-cloud-init.yaml` was updated to persist the server-side route and DNS preference
- `proxmox` legacy `192.168.1.11` address was removed from `vmbr0`; the host now remains reachable only on `192.168.50.11`, `192.168.40.11`, and `192.168.30.11`
- `ubuntu` legacy `192.168.1.61` address was removed from `enp6s18`; the host now remains reachable on `192.168.50.61` and `192.168.30.61`
- `truenas` legacy `192.168.1.12` address was removed from `enp6s17` using the TrueNAS interface rollback/checkin workflow; the host now remains reachable on `192.168.50.12` and `192.168.40.12`
- `grizzley` Wi-Fi config was removed, leaving wired server-side operation on `192.168.50.84` plus its VLAN-side service addresses
- `ice` Wi-Fi config was removed, leaving wired server-side operation on `192.168.50.197` plus its VLAN-side service addresses
- `truenas`, `grizzley`, and `ice` staging-side `192.168.40.x` addresses were removed
Verification after the change:
- SSH remained reachable on both `192.168.50.12` and `192.168.1.12`
- Default route now points to `192.168.50.1` on `enp6s19`
- Internet egress test to `1.1.1.1` succeeded
- `proxmox` remained reachable on both `192.168.50.11` and `192.168.1.11`
- `ubuntu` remained reachable on both `192.168.50.61` and `192.168.1.61`
- `gitea.tophermayor.com` and `opencode.tophermayor.com` continued returning `HTTP 200`
- after the Proxmox legacy-address removal, SSH remained reachable on `192.168.50.11` and no longer responded on `192.168.1.11`
- after the Ubuntu legacy-address removal, SSH remained reachable on `192.168.50.61`, critical app endpoints continued returning `HTTP 200`, and the old `192.168.1.61` SSH path stopped responding
- after the TrueNAS legacy-address removal, SSH remained reachable on `192.168.50.12`, the old `192.168.1.12` path stopped responding, and interface changes were checked in successfully
- after the `grizzley` and `ice` Wi-Fi removals, SSH remained reachable on `192.168.50.84` and `192.168.50.197`, while the old Wi-Fi IPs no longer responded from the management host
Still pending for full TrueNAS normalization:
- no host-side `192.168.40.12` path remains
Still pending for full Proxmox and Ubuntu normalization:
- update stale controller/client observations so UniFi no longer shows the old `192.168.1.61` path as active after the host-side removal
Still pending for full Grizzley and Ice normalization:
- allow UniFi client state to age out or refresh, since disconnected Wi-Fi client observations may remain visible briefly after host-side removal
- decide whether their additional VLAN-side service addresses on `192.168.30.x` remain intentional long-term

65
homelab/docs/unifi-live-drift-table.md Normal file
View File

@@ -0,0 +1,65 @@
---
project:
name: UniFi Live Drift Table
status: planning
category: infrastructure
source: homelabagentroot
created: 2026-03-17
updated: 2026-03-17
description: Drift table comparing live UniFi observations to authoritative host repo and catalog intent
goals:
- Identify address and zone drift for infrastructure hosts
- Separate intentional split-plane designs from accidental placement
- Provide a decision aid before firewall cleanup execution
priority: high
tags: [unifi, drift, hosts, planning, audit]
---
# UniFi Live Drift Table
## Summary
This table compares live UniFi observations from 2026-03-17 with the latest pulled host repos and homelab catalogs.
| Host / Asset | Authoritative Intent | Live UniFi Observation | Drift Level | Decision Needed |
|--------------|----------------------|------------------------|-------------|-----------------|
| `ubuntu` | `192.168.50.61`, primary Docker/app edge | host now routes and serves from `192.168.50.61`; UniFi currently reports the MAC on another VLAN-side address | Low | Refresh controller/client state so UniFi reflects the completed host-side removal |
| `grizzley` | `192.168.50.84`, edge ingress/control node | host now routes from `192.168.50.84`; UniFi may still show stale/disconnected Wi-Fi history for `192.168.10.145` | Low | Confirm whether any residual Wi-Fi client state ages out cleanly |
| `ice` | `192.168.50.197`, control-plane host | host now routes from `192.168.50.197`; UniFi may still show stale/disconnected Wi-Fi history for `192.168.10.178` | Low | Confirm residual Wi-Fi client state ages out cleanly |
| `proxmox` | `192.168.50.11`, infra-only hypervisor | `192.168.50.11`; legacy `192.168.1.11` removed | Low | Keep monitoring hosted service paths |
| `truenas` | `192.168.50.12`, storage-only host | `192.168.50.12`; default route prefers `192.168.50.1` | Low | Keep monitoring storage-path behavior |
| `panda` app plane | `192.168.30.196` | `192.168.30.196` | Low | Keep |
| `panda` admin plane | `192.168.50.196` SSH endpoint | not shown in current client list | Low | Keep and validate by access test, not client inventory alone |
| `traefik-lxc` | `192.168.50.115` | not queried directly in client output | Medium | Validate server-segment reachability and access scope |
| `alpine-adguard` | `192.168.50.157` | not queried directly in client output | Medium | Validate DNS/admin access scope |
## Staged-Cutover Notes
- `grizzley` Wi-Fi path now has a staged reservation for `192.168.10.145`
- `ice` now has staged reservations for both `192.168.10.178` and `192.168.50.197`
- `homeassistant` now has an active staged reservation for `192.168.30.196`
- `ubuntu` and `proxmox` were corrected by switching to the legacy fixed-IP update format accepted by the classic UniFi endpoint
- `truenas` conflict was traced to a second NIC record that had reserved `192.168.1.145`; that stale fixed-IP reservation has been cleared, while the active primary reservation at `192.168.1.12` remains valid
- `truenas` host egress now prefers `192.168.50.1`, and the legacy `192.168.1.12` address has been removed
- `grizzley` and `ice` Wi-Fi reservations were cleared after host-side Wi-Fi removal, but UniFi may still report the disconnected records until controller state refreshes
- `ubuntu` host-side removal of `192.168.1.61` is complete, but UniFi currently reports the MAC on another VLAN-side address, which appears to be a controller observation artifact for a multi-VLAN host
- staging-side host addresses were removed from `truenas`, `grizzley`, and `ice`, and the two explicit staging firewall policies were disabled
## Interpretation
- High drift means live UniFi placement materially conflicts with the intended trust boundary in the authoritative repos.
- Medium drift means the placement may be legitimate, but it still needs explicit documentation and tighter firewall policy.
- Low drift means the live state matches the intended design closely enough for now.
## Most Important Drift Items
1. `ubuntu` carries your primary public and internal app edge, so its current `Default`-side visibility has the biggest security impact.
2. `proxmox` and `truenas` should not sit in a broadly reachable user or legacy management segment unless there is a deliberate operational reason.
3. `grizzley` and `ice` appearing on `Family of D.` weakens the intended separation between user devices and infrastructure nodes.
4. `panda` is the cleanest example of an intentional split-plane design and can be used as a model for how to document exceptions.
## Remaining 192.168.30.x Assessment
- `ubuntu`, `proxmox`, `grizzley`, and `ice` still expose `192.168.30.x` addresses
- Those addresses were retained intentionally in this cleanup wave because they are more likely to back IoT-side service access than the removed legacy `192.168.1.x` or staging `192.168.40.x` paths
- Removing them should be a per-service maintenance task, not a bulk cleanup operation

362
homelab/docs/unifi-network-optimization-plan.md Normal file
View File

@@ -0,0 +1,362 @@
---
project:
name: UniFi Network Performance and Security Optimization Plan
status: planning
category: infrastructure
source: homelabagentroot
created: 2026-03-16
updated: 2026-03-17
description: Planning-only document for UniFi segmentation, firewall optimization, and host placement based on live controller data
goals:
- Define a recommended target zone matrix for trusted, guest, IoT, staging, server, and VPN traffic
- Identify firewall policies to keep, tighten, or retire without applying live changes yet
- Map homelab hosts and service classes to the best VLAN and SSID strategy
priority: high
tags: [unifi, network, firewall, performance, security, planning]
---
# UniFi Network Performance and Security Optimization Plan
## Overview
This document captures recommended UniFi network improvements based on a live controller review performed on 2026-03-17 and a same-day pull of the latest authoritative host repositories.
This is a planning document only.
- No firewall policies, zones, VLAN assignments, SSIDs, or client placements were changed while preparing this document.
- Current-state notes are based on live UniFi data available from the local controller at `https://192.168.1.1`.
- Host placement recommendations were cross-checked against the latest pulled host repos for `ubuntu`, `grizzley`, `ice`, `proxmox`, `truenas`, and `panda`.
- Existing cleanup work in [[../tasks/unifi-firewall-cleanup-plan.md|UniFi Firewall Cleanup Plan]] should be treated as historical context, not the final source of truth for the current live posture.
## Live Snapshot
### Controller and Inventory
- Controller: UniFi Cloud Gateway Ultra (`UDRULT`)
- UniFi Network version: `10.1.85`
- UniFi devices currently visible: `4`
- Live clients currently visible: `43`
- Wireless networks currently visible: `3`
- VPN servers currently visible: `1` (`UGC WireGuard`)
### Current Network and Zone Mapping
| Network | Subnet | VLAN | Current Zone | Notes |
|--------|--------|------|--------------|-------|
| Default | 192.168.1.0/24 | native | Management | Contains core infrastructure today |
| Family of D. | 192.168.10.0/24 | 10 | Internal | Trusted user devices now separated from Management |
| Will of D. (Guest) | 192.168.20.0/24 | 20 | Guest | Good logical placement |
| Will of D. IoT | 192.168.30.0/24 | 30 | IoT | Good logical placement |
| Staging | 192.168.40.0/24 | 40 | Staging | Good logical placement |
| Production | 192.168.50.0/24 | 50 | Servers | Good logical placement |
| UGC WireGuard | 192.168.4.0/24 | n/a | Vpn | Keep as a dedicated VPN trust boundary |
### Implementation State
First-wave UniFi changes were applied on 2026-03-17:
- `Family of D.` was moved from `Management` into `Internal`
- `Management` was reduced to `Default` only
- New `Internal` user-defined allow rules were created for:
- `Internal -> Servers HTTPS`
- `Internal -> Servers HTTP`
- `Internal -> IoT`
- `Internal -> Staging`
- Logging was enabled on selected user-defined edge and VPN policies:
- `Allow External to Web Proxy`
- `Vpn to Management`
- `MBA VPN to Management`
- `Vpn to Servers`
- `Vpn to IoT`
- Logging was also enabled on selected user-defined east-west policies for observability:
- `Management to Servers`
- `Management to IoT`
- `Management to Guest`
- `Internal to Servers HTTPS`
- `Internal to Servers HTTP`
- `Internal to IoT`
- `Internal to Staging`
- `IoT to Jellyfin`
- `IoT to Traefik`
- Staged reservation cleanup succeeded for:
- `ubuntu` -> `192.168.1.61`
- `proxmox` -> `192.168.1.11`
- `grizzley` -> `192.168.10.145`
- `ice` -> `192.168.10.178` and `192.168.50.197`
- `homeassistant` -> `192.168.30.196`
- First host-side migration execution succeeded for `truenas` by moving its default route to `192.168.50.1` while preserving reachability on both `192.168.50.12` and `192.168.1.12`
- First host-side migration execution also succeeded for `proxmox` and `ubuntu` by moving their active default routes to `192.168.50.1` while preserving SSH reachability on both their legacy and server-side addresses
- Final legacy-address removal has now succeeded for `proxmox`, `ubuntu`, and `truenas` on the old `192.168.1.x` paths
- Dual-network cleanup succeeded for `grizzley` and `ice` by removing active Wi-Fi participation on `Family of D.`
- Staging-side `192.168.40.x` host paths have been removed from `truenas`, `grizzley`, and `ice`
Two system-defined port-forward policies were not modified because the controller rejects edits to them via the integration API:
- `Allow Port Forward HTTP`
- `Allow Port Forward HTTPS`
### Immediate Current-State Risks
- Several homelab hosts still appear on more than one network, or have records that suggest multiple interfaces. That is useful when intentional, but it reduces the value of zone-based policy if it is not tightly documented.
- The stale secondary TrueNAS reservation at `192.168.1.145` has now been cleared, and the legacy `192.168.1.12` host address has been removed.
- UniFi client inventory can still lag behind host-side changes when a single MAC participates in multiple VLANs; current stale observations should be treated as controller state lag unless they persist after refresh/age-out.
- The remaining host-side cleanup question is whether the infrastructure `192.168.30.x` service-side addresses are all intentionally needed; they were retained in this wave as the conservative default pending per-service validation.
- Logging is now enabled on selected user-defined edge and VPN policies, but many block rules and system-defined edge rules still do not log.
- Internet-facing exposure still exists for reverse proxy traffic, including `HTTP` and `HTTPS`, and should be reviewed for minimum required surface area.
## Authoritative Host Repo Alignment
The latest pulled host repos describe the intended authoritative network identity below. Where live UniFi observations differ, that drift should be treated as a design and documentation issue to resolve before major firewall cleanup.
| Host | Authoritative Repo Intent | Live UniFi Observation | Planning Impact |
|------|---------------------------|------------------------|-----------------|
| ubuntu | `192.168.50.61`, primary Docker host, primary Traefik, Gitea, Vaultwarden, Authentik, OpenCode | currently visible at `192.168.1.61` | Highest-priority host placement drift because many public and internal services depend on it |
| grizzley | `192.168.50.84`, Pi edge ingress | currently visible at `192.168.10.145`, with another extra live record | Edge ingress should not share a user-trust segment unless explicitly intended |
| ice | `192.168.50.197`, control-plane OpenCode | visible at `192.168.50.197` and `192.168.10.178` | Dual placement weakens the meaning of `Servers` versus user-trusted access |
| proxmox | `192.168.50.11`, hypervisor | currently visible at `192.168.1.11` | Hypervisor should remain in an infrastructure-only network |
| truenas | `192.168.50.12`, storage-only host | visible at `192.168.1.12` and also referenced as `192.168.50.12` | Storage admin paths should be explicit and documented if multi-homed |
| panda | Home Assistant UI at `192.168.30.196`, SSH endpoint at `192.168.50.196` | live Home Assistant client at `192.168.30.196`; separate admin SSH endpoint not shown in client list | This is a valid split-access pattern and should be preserved intentionally |
### What The Latest Host Repos Change In This Plan
- `ubuntu` is more security-sensitive than the first draft implied because its latest host repo now clearly tracks hardened public edge, `Gitea`, and `Vaultwarden` state. That raises the priority of narrowing public exposure and protecting admin paths.
- `grizzley` and `ice` are clearly intended to be `Servers`-zone infrastructure nodes in their host repos, so their current appearances on `Family of D.` should be treated as drift unless there is a deliberate dual-network design.
- `panda` is not simply an IoT appliance. The latest host repo explicitly documents an app endpoint on `192.168.30.196` and a separate SSH/admin endpoint on `192.168.50.196`, which supports keeping Home Assistant functionally close to IoT while retaining a cleaner administrative path.
- `proxmox` is not just a hypervisor endpoint. Its latest repo also documents server-side infrastructure such as `traefik-lxc` at `192.168.50.115`, `alpine-adguard` at `192.168.50.157`, and other server-segment workloads that should stay out of user and guest networks.
- `truenas` latest repo content is partially historical, but the broader homelab catalogs and current host metadata still point to `192.168.50.12` as the intended storage address. The plan should therefore prefer the `Production`/server-side path over the current `Default` visibility.
## Recommended Target Zone Matrix
### Recommended Zone Roles
| Zone | Recommended Networks | Purpose |
|------|----------------------|---------|
| Management | Default | Admin workstations, controller access, network gear, hypervisor, storage |
| Internal | Family of D. | Trusted daily-use family devices |
| Guest | Will of D. (Guest) | Visitor and untrusted personal devices |
| IoT | Will of D. IoT | Smart home and appliance-style devices |
| Staging | Staging | Lab, test, and temporary workloads |
| Servers | Production | Public and internal homelab application hosts |
| Vpn | UGC WireGuard | Remote admin and controlled remote access |
| External | WANs | Internet |
### Recommended Connectivity Matrix
| From -> To | Management | Internal | Guest | IoT | Staging | Servers | Vpn | External |
|------------|------------|----------|-------|-----|---------|---------|-----|----------|
| Management | Allow | Limited | Limited | Allow | Allow | Allow | Allow | Allow |
| Internal | Deny by default | Allow | Deny | Limited | Limited | Limited | Deny | Allow |
| Guest | Deny | Deny | Allow | Deny | Deny | Deny | Deny | Allow |
| IoT | Deny | Deny | Deny | Allow | Deny | Limited | Deny | Allow |
| Staging | Limited | Limited | Deny | Deny | Allow | Allow | Deny | Allow |
| Servers | Limited | Return only | Deny | Limited | Allow | Allow | Deny | Allow |
| Vpn | Limited | Deny by default | Deny | Limited | Limited | Allow | Allow | Allow |
### Matrix Interpretation
- `Management` should be the only zone with broad administrative reach.
- `Internal` should access `Servers` through specific app ports and URLs, not broad all-port access.
- `Guest` should have internet access only.
- `IoT` should keep internet access plus narrow exceptions for services such as media streaming, reverse proxy access, and Home Assistant as needed.
- `Vpn` should be treated as a separate zone, not as implicit `Management`. Default VPN access should reach only the minimum required destinations.
## Firewall Recommendation Set
The live policy export reported `236` total policies. The visible slice used for this review showed `102` `ALLOW` and `98` `BLOCK` policies in the first `200` entries. Recommendations below focus on the posture that was visible live and should be validated against a full export before any change window.
### Keep
Keep these rule patterns, assuming they are already scoped correctly to the intended hosts and ports:
- System defaults such as `Block Invalid Traffic`, `Block All Traffic`, and `Allow Return Traffic`
- `Guest -> External`
- Intra-zone traffic where explicitly needed (`Internal`, `Guest`, `IoT`, `Servers`)
- Reverse proxy ingress to the public web entry point over `HTTPS`
- Narrow published access for `Gitea` and `Vaultwarden` behind the hardened public edge on `ubuntu`
- Narrow `IoT -> Servers` exceptions for media and automation services such as Jellyfin, Traefik, and Home Assistant
- `Vpn -> Servers` for approved administrative and remote-access workflows
### Tighten
These items present the best mix of security and operational benefit:
1. Separate `Family of D.` from `Management`
- Move `Family of D.` out of `Management` and into `Internal`
- Do this before treating `Management` rules as a true admin trust boundary
2. Restrict VPN reach
- Keep `Vpn -> Servers` for normal remote admin
- Narrow `Vpn -> Management` to only the ports and hosts needed for network and infrastructure administration
- Narrow `Vpn -> IoT` to specific automation and troubleshooting needs only
3. Reduce internet-facing exposure
- Keep `HTTPS` ingress for the reverse proxy
- Keep `HTTP` only if it is still required for redirect handling or ACME validation
- Replace any broad `External -> Servers` or `External -> Web Proxy` rules with host and port scoped rules where possible
- Prioritize review of the `ubuntu` edge because that host now clearly carries `Traefik`, `Gitea`, and `Vaultwarden` in the latest host repo
4. Reduce rule overlap and duplication
- Review overlapping VPN rules such as `Vpn to Servers` and `Allow WireGuard to Services (Fixed)`
- Review repeated return-path rules such as the visible duplicate `Management to IoT (Return)` entries
- Prefer one clearly named policy per intent over multiple partially overlapping policies
5. Turn on useful logging
- Enable logging on selected block rules and edge-facing allow rules
- Minimum recommended logging targets: `External -> *`, `Vpn -> Management`, `Vpn -> Servers`, and denied `Guest` or `IoT` inter-zone attempts
### Retire After Validation
Retire or replace these rule patterns only after confirming there is no hidden dependency:
- Broad all-port `Internal -> Servers` allow rules
- Broad all-port `IoT -> Servers` allow rules that are no longer needed once application-specific exceptions exist
- Duplicate return-path rules that do not add new behavior
- `HTTP` port-forward exposure if `HTTPS` plus redirect/ACME alternatives cover the same use case
- Legacy rules tied to decommissioned hosts, empty zones, or old service names
### Naming and Policy Hygiene
Use policy names that always match the real source, destination, and purpose.
Recommended naming pattern:
`<source zone> -> <destination zone> | <service or intent> | <action>`
Examples:
- `Internal -> Servers | HTTPS apps | ALLOW`
- `IoT -> Servers | Jellyfin 8096 | ALLOW`
- `Guest -> Internal | default deny | BLOCK`
- `Vpn -> Management | admin https | ALLOW`
## Recommended Host and Service Placement
### Core Homelab Hosts
| Asset | Current Observed Placement | Recommended Placement | Access Model | Notes |
|------|-----------------------------|-----------------------|--------------|-------|
| UniFi gateway and AP management IPs | Default | Management | Admin only | Keep network gear on the management network |
| Proxmox | Default (`192.168.1.11`) | Management or dedicated infrastructure VLAN, wired | Management and VPN only | Latest host repo still treats Proxmox as infrastructure-only; also protect its hosted `traefik-lxc` and `adguard` style workloads |
| TrueNAS | Default (`192.168.1.12`), plus preferred lookup for `192.168.50.12` | Management primary, optional secondary storage path only if intentional | Management and selected servers | Prefer the documented `192.168.50.12` server-side identity and document any secondary path explicitly |
| Ubuntu primary Docker host | Default (`192.168.1.61`) | Servers long-term, or documented dual-home during migration | Internal via reverse proxy, Management for admin | Latest host repo confirms this host carries the primary public edge plus `Gitea`, `Vaultwarden`, Authentik, and core apps |
| Grizzley | Family (`192.168.10.145`), plus another live record | Servers, wired | Reverse proxy and admin paths only | Latest host repo intent is Pi edge ingress and control traffic, not consumer trusted-client placement |
| Ice | Production (`192.168.50.197`) and Family (`192.168.10.178`) | Servers primary, optional dedicated management path only if justified | Management and approved service paths | Latest host repo intent is control-plane infrastructure, so current family-network presence should be treated as drift until justified |
| Panda / Home Assistant OS | live Home Assistant endpoint at `192.168.30.196`; latest host repo also documents SSH at `192.168.50.196` | Keep app plane in IoT; keep admin plane on server/management side | Management, Internal, and selected IoT flows | This split model is preferable to exposing full Home Assistant administration on a user or guest network |
### Additional Server-Segment Assets From Latest Host Repos
| Asset | Documented Address | Recommended Zone | Notes |
|------|--------------------|------------------|-------|
| Proxmox `traefik-lxc` | `192.168.50.115` | Servers | Keep isolated from `Internal` except through intended app ports |
| Proxmox `alpine-adguard` | `192.168.50.157` | Servers or Management | DNS infrastructure deserves tighter access than general apps |
| Home Assistant SSH admin endpoint | `192.168.50.196` | Management or Servers | Keep SSH/admin access distinct from the IoT-side app endpoint |
### Service Placement Guidance
| Service Class | Recommended Zone | Client Access Pattern |
|--------------|------------------|-----------------------|
| Reverse proxy / ingress (Traefik) | Servers | `Internal`, `Management`, and approved `Vpn` clients over `80/443` |
| Public identity and secrets apps (`Authentik`, `Gitea`, `Vaultwarden`) | Servers | `Management` and `Internal` over `HTTPS`; expose externally only through tightly scoped edge policies |
| Storage and virtualization admin (TrueNAS, Proxmox) | Management | `Management` and limited `Vpn` only |
| Media services (Jellyfin and related) | Servers | `Internal` by default, `IoT` only for TVs, streamers, and casting targets that need it |
| Home automation (Home Assistant) | IoT app plane plus management-side SSH/admin plane | `Management`, selected `Internal`, selected `IoT` |
| Test workloads | Staging | `Management`, selected `Internal`, and `Servers` as required |
### Client and SSID Placement Guidance
| Client Type | Recommended Network | Recommended SSID Strategy | Notes |
|-------------|---------------------|---------------------------|-------|
| Primary family phones, tablets, laptops | Internal (`Family of D.`) | `Family of D.` | Trusted user devices should not live in `Management` |
| Visitors | Guest | `Will of D.` | Keep internet-only |
| TVs, speakers, streamers, thermostats, hubs, plugs, lamps | IoT | `Will of D. IoT` | Keep appliance devices isolated and use narrow service exceptions |
| Baby monitors | IoT | `Will of D. IoT` | Current live placement in `Family of D.` should be reviewed and likely moved |
| Admin workstation(s) | Internal by default; optional future dedicated admin SSID/VLAN | `Family of D.` today | Add a dedicated admin network only if there is a real operational need |
## Performance Recommendations
### Wireless Design
- Keep SSID count low. The current three-SSID model is reasonable and should scale better than adding more SSIDs unless there is a strong operational need.
- Keep `Family of D.` optimized for higher-performance personal devices on `5 GHz` and `6 GHz` where supported.
- Keep `Will of D. IoT` focused on reliability rather than peak throughput. Many smart devices behave better on `2.4 GHz`, and mixed-band IoT SSIDs should be reviewed carefully for compatibility issues.
- Keep guest traffic off trusted SSIDs. That protects airtime and reduces unnecessary broadcast and discovery noise on the primary user network.
- For voice and discovery reliability, use `Multicast to Unicast` on user SSIDs that need iPhone calling or nearby device discovery.
- Keep `Multicast and Broadcast Blocker` off on user SSIDs unless there is a specific, tested reason to suppress discovery traffic.
- If roaming quality matters for voice devices, prefer `Fast Roaming` plus `BSS Transition` on trusted SSIDs and validate client behavior after each change.
### Verified SSID Posture
The live UniFi controller was updated on 2026-04-13 to support iPhone WiFi calling and gate control traffic.
| SSID | Multicast to Unicast | Fast Roaming | BSS Transition | Multicast/Broadcast Blocker |
|------|----------------------|--------------|----------------|-----------------------------|
| `Will of D.` | enabled | enabled | enabled | off |
| `Will of D. IoT` | enabled | disabled | enabled | off |
| `Family of D.` | enabled | enabled | enabled | off |
| `Will of D. IoT 2.4G` | enabled | n/a | enabled | off |
This aligns the trusted SSID with the same multicast and roaming posture already used on `Family of D.`.
### Wired and Infrastructure Placement
- Prefer wired-only placement for infrastructure hosts wherever possible.
- Reduce or eliminate unintended dual-homed infrastructure. A host that sits in multiple trust zones is harder to reason about and easier to misconfigure.
- Keep reverse proxy, server, and storage paths off Wi-Fi entirely.
### Network Hygiene That Helps Performance Too
- Move non-user appliance devices, especially the visible baby monitors, out of `Family of D.` and into `IoT`.
- Keep media exceptions narrow so background service discovery does not become broad east-west traffic.
- Review AP client distribution and radio settings only after collecting AP-side statistics, since transmit power and minimum RSSI changes should be data-driven.
## Security Recommendations
### Highest-Priority Changes to Plan
1. Re-establish `Management` as a real infrastructure-only trust boundary
2. Turn on useful firewall logging for edge and deny rules
3. Move live host addressing closer to the authoritative host repo intent for `ubuntu`, `grizzley`, `ice`, `proxmox`, and `truenas`
4. Narrow VPN access to the smallest practical set of hosts and ports
5. Review and minimize all public `HTTP` exposure, especially around the `ubuntu` public edge
6. Remove or consolidate duplicate and overlapping allow rules
### Medium-Priority Changes to Plan
1. Re-home server-class hosts so they align with the intended `Servers` zone
2. Review whether Home Assistant should remain in `IoT` or move to a dedicated automation segment later
3. Audit wildcard DNS usage to confirm only intended clients can reach sensitive admin applications
4. Decide whether `panda`'s split app/admin path should become the standard pattern for other appliance-style services
## Proposed Rollout Order
No changes have been applied yet. When this work is scheduled, the lowest-risk order is:
1. Export and back up current zones and policies
2. Enable logging on selected deny and edge allow rules
3. Reconcile live host IP placement with the latest authoritative host repos
4. Correct the `Management` versus `Internal` network assignments
5. Move obvious consumer/IoT devices out of `Family of D.`
6. Review and remove duplicate or overly broad firewall policies
7. Re-home server-class hosts where needed
8. Re-test reverse proxy, media, Home Assistant, VPN, and admin paths after each change set
## Open Questions Before Execution
- Should the Ubuntu primary Docker host stay on `Default` for operational simplicity, or should it move fully into `Servers`?
- Are the extra `grizzley` and `ice` live placements intentional dual-homing, or leftover records/interfaces to clean up?
- Should `proxmox` and `truenas` keep any `Default`-side presence, or should they be normalized to their documented `192.168.50.x` identities?
- Is public `HTTP` still required for any production workflow?
- Does Home Assistant need to remain on `IoT`, or is the current split model of IoT app access plus management-side SSH the desired long-term pattern?
## Decision Summary
If no larger redesign is desired, the minimum high-value outcome is:
- `Management` = infrastructure only
- `Internal` = family/trusted user devices
- `Guest` = internet only
- `IoT` = appliances with narrow exceptions
- `Servers` = homelab application hosts
- `Vpn` = remote access with explicit least-privilege rules
That structure provides the clearest improvement in both security and troubleshooting without requiring a full network rebuild.

64
homelab/docs/unifi-post-migration-summary-2026-03-17.md Normal file
View File

@@ -0,0 +1,64 @@
---
project:
name: UniFi Post-Migration Summary 2026-03-17
status: active
category: infrastructure
source: homelabagentroot
created: 2026-03-17
updated: 2026-03-17
description: Final summary of UniFi zoning, host migration, and rollback references after the March 17 cleanup wave
goals:
- Record the end state after network cleanup
- Provide a quick reference for what changed and what remains
- Link operators to rollback and runbook notes
priority: high
tags: [unifi, post-migration, summary, rollback]
---
# UniFi Post-Migration Summary 2026-03-17
## Completed Changes
- `Family of D.` moved from `Management` to `Internal`
- `Management` reduced to `Default` only
- New `Internal` access rules created for `Servers`, `IoT`, and `Staging`
- Logging enabled on key edge, VPN, and east-west user-defined policies
- Legacy `192.168.1.x` host paths removed from:
- `proxmox`
- `ubuntu`
- `truenas`
- Wi-Fi participation removed from:
- `grizzley`
- `ice`
- Staging-side `192.168.40.x` host paths removed from:
- `truenas`
- `grizzley`
- `ice`
- Staging access policies disabled:
- `Vpn to Staging`
- `Allow Servers to Staging`
## Current Host End State
| Host | Current Primary Addressing | Notes |
|------|----------------------------|-------|
| `ubuntu` | `192.168.50.61`, `192.168.30.61` | App edge healthy; UniFi may still show stale alternate observations |
| `proxmox` | `192.168.50.11`, `192.168.30.11` | Legacy `192.168.1.11` removed |
| `truenas` | `192.168.50.12` | Legacy `192.168.1.12` and staging `192.168.40.12` removed |
| `grizzley` | `192.168.50.84`, `192.168.30.84` | Wi-Fi removed |
| `ice` | `192.168.50.197`, `192.168.30.197` | Wi-Fi removed |
## Remaining Follow-Up
- Allow UniFi controller client history to age out or refresh
- Keep remaining `192.168.30.x` service-side paths in place for now because they appear to support intentional IoT-side service adjacency; remove them only after per-service validation
- Review public `HTTP` exposure and any duplicate firewall rules
- `grizzley` still has one disconnected/no-IP UniFi history record; a direct delete attempt returned `api.err.NotFound`, so this currently looks like controller-history lag
- `TrueNAS` is intentionally exposed through the local-only route `truenas.local.tophermayor.com`; `truenas.tophermayor.com` is not the canonical admin URL
## References
- Canonical current-state reference: [`docs/UNIFI_NETWORK_INFRASTRUCTURE.md`](/Users/christopherjohnsisonmayor/Infrastructure/core/docs/UNIFI_NETWORK_INFRASTRUCTURE.md)
- Runbook: [[unifi-host-migration-runbook.md|UniFi Host Migration Runbook]]
- Rollback: [[unifi-rollback-2026-03-17.md|UniFi Rollback 2026-03-17]]
- Execution details: [[unifi-execution-plan.md|UniFi Execution Plan]]

79
homelab/docs/unifi-rollback-2026-03-17.md Normal file
View File

@@ -0,0 +1,79 @@
---
project:
name: UniFi Rollback 2026-03-17
status: active
category: infrastructure
source: homelabagentroot
created: 2026-03-17
updated: 2026-03-17
description: Rollback notes for the first UniFi zone and policy changes applied on 2026-03-17
goals:
- Restore pre-change zone membership if needed
- Record new policy IDs created during the first change wave
- Provide a safe reference before the next production network cutover
priority: high
tags: [unifi, rollback, firewall, zones, change-management]
---
# UniFi Rollback 2026-03-17
## Backups
Pre-change snapshots were saved to:
- `/private/tmp/unifi-change-backups-20260317/zones-before.json`
- `/private/tmp/unifi-change-backups-20260317/policies-before.json`
## Changes Applied
### Zone Changes
Before:
- `Management` -> `Default`, `Family of D.`
- `Internal` -> empty
After:
- `Management` -> `Default`
- `Internal` -> `Family of D.`
### New User-Defined Policies Created
| ID | Name |
|----|------|
| `ccc50b02-81ee-4e85-a994-87228b28d6ef` | `Internal to Servers HTTPS` |
| `07e03549-c022-4e90-981d-154269dc0471` | `Internal to Servers HTTP` |
| `6a7c0209-3d75-4826-bc61-ab98d9fe3ce3` | `Internal to IoT` |
| `977017d1-7600-48b1-9f04-e76eed01ca2c` | `Internal to Staging` |
### Existing Policies Modified
Logging enabled on:
- `89de6586-d284-4ce0-8e1f-8fea428c4af4` `Allow External to Web Proxy`
- `b13ad681-3d4c-4cb0-b186-70678087ddc9` `Vpn to Management`
- `92c1b619-ef7e-4b74-aaca-e57851abe962` `MBA VPN to Management`
- `5e6f26c2-1487-4e92-b682-6bcbb987b913` `Vpn to Servers`
- `3b64e36a-a452-4ab0-96b5-6088efb2330c` `Vpn to IoT`
## Rollback Steps
If the `Family of D.` cutover needs to be reversed before the next maintenance window:
1. Move `Family of D.` back into `Management`
2. Remove `Family of D.` from `Internal`
3. Keep the new `Internal` user-defined rules disabled or delete them if they are no longer needed
4. Re-test access from a `192.168.10.x` client to `Servers`, `IoT`, and `Staging`
## Rollback Zone State
Desired rollback state:
- `Management` -> `bcf0598f-9361-4306-9024-9817fd841836`, `fb44c9bf-1534-4a98-9c7e-6aee4bf4069a`
- `Internal` -> no networks assigned
## Notes
- `policies-before.json` is only a `200/236` visible slice from the original tool output; use live API reads plus the saved zone snapshot for the most accurate rollback reference.
- System-defined edge rules such as `Allow Port Forward HTTP` and `Allow Port Forward HTTPS` were not modified.

198
homelab/docs/unifi-wifi-calling-optimization.md Normal file
View File

@@ -0,0 +1,198 @@
---
project:
name: WiFi Calling Optimization Runbook
status: completed
category: infrastructure
source: homelabagentroot
created: 2026-04-01
updated: 2026-04-01
description: Live configuration and runbook for AT&T WiFi calling optimization on UniFi UCG Ultra
carrier: AT&T
affected_ssids: [Family of D., Will of D. (Guest)]
affected_vlans: [10, 20, 40, 50, 1]
tags: [unifi, wifi, wifi-calling, att, qos, 802.11r]
---
# WiFi Calling Optimization Runbook
## Overview
Optimizations applied to the UniFi Cloud Gateway Ultra (UCG Ultra) to support reliable AT&T WiFi calling across all non-IoT VLANs.
**Applied:** 2026-04-01
**Controller:** `https://192.168.1.1` (UniFi Network 10.1.85)
**Site ID:** `88f7af54-98f8-306a-a1c7-c9349722b1f6`
## AT&T WiFi Calling Requirements
AT&T WiFi calling uses IPSec/IKEv2 tunnels to AT&T infrastructure:
| Protocol | Port | Purpose |
|----------|------|---------|
| IKEv2 | UDP 500 | Key exchange and tunnel establishment |
| IPSec NAT-T | UDP 4500 | Encapsulated ESP through NAT |
| SIP (fallback) | UDP/TCP 5060, 5061 | Session initiation (rarely used by AT&T) |
| RTP Media | UDP 10000-20000 | Voice media (inside IPSec tunnel) |
**Key insight:** RTP media is encrypted inside the IPSec tunnel, so DSCP marking on outer packets has limited effect. The biggest quality improvements come from:
1. Fast roaming (802.11r) to eliminate AP handoff gaps
2. Reducing airtime contention (multicast-to-unicast)
3. Ensuring firewall allows all required ports
## Changes Applied
### 1. Family of D. SSID (`b2784680-7b04-4c8a-9098-19aced53fc89`)
**API:** `PUT /sites/{siteId}/wifi/broadcasts/b2784680-7b04-4c8a-9098-19aced53fc89`
| Setting | Before | After | Impact |
|---------|--------|-------|--------|
| `fastRoamingEnabled` | `false` | `true` | 802.11r - eliminates re-auth gap during AP roaming |
| `wpa3FastRoamingEnabled` | `false` | `true` | WPA3 Fast Transition for WPA3-only clients |
| `multicastToUnicastConversionEnabled` | `false` | `true` | Reduces airtime waste from mDNS/SSDP broadcasts |
**Already enabled (unchanged):**
- `bandSteeringEnabled`: `true` - prefers 5/6GHz over 2.4GHz
- `bssTransitionEnabled`: `true` - 802.11v neighbor reports
- `broadcastingFrequenciesGHz`: `[5, 6, 2.4]` - tri-band
### 2. Will of D. Guest SSID (`a2cdccb6-d054-47ad-ab14-62cae625b6af`)
**API:** `PUT /sites/{siteId}/wifi/broadcasts/a2cdccb6-d054-47ad-ab14-62cae625b6af`
| Setting | Before | After | Impact |
|---------|--------|-------|--------|
| `bssTransitionEnabled` | `false` | `true` | 802.11v - helps guest devices roam efficiently |
**Not changed on Guest:**
- `fastRoamingEnabled`: remains `false` (guest devices typically don't need 802.11r)
- `multicastToUnicastConversionEnabled`: remains `false`
### 3. Traffic Matching Rule
**API:** `POST /sites/{siteId}/traffic-matching-lists`
| Property | Value |
|----------|-------|
| Name | `WiFi Calling Ports` |
| ID | `e7f06077-1a11-4355-88df-185837ba29df` |
| Type | `PORTS` |
| Ports | UDP 500, 4500, 5060, 5061 |
**Note:** RTP port range (10000-20000) was not added because the UniFi integration API does not support `PORT_NUMBER_RANGE` in traffic matching list items. The signaling ports (500, 4500) are the most critical for tunnel establishment.
## Firewall Verification
All zones already have outbound access to External (internet), so no firewall changes were needed:
| Zone | External Access | Status |
|------|----------------|--------|
| Internal (`1c79c8c2`) | Allow All Traffic (system) | OK |
| Guest (`b8d0e4f2`) | Guest to External (idx 10000) + fallback | OK |
| Staging (`dc406f85`) | Allow All Traffic (system) | OK |
| Management (`ea466cdf`) | Allow All Traffic (system) | OK |
| DMZ (`4fb011b4`) | Allow All Traffic (system) | OK |
## Current SSID Configuration (Post-Optimization)
| SSID | Bands | Security | Fast Roaming | BSS Transition | Mcast→Ucast |
|------|-------|----------|--------------|----------------|-------------|
| Family of D. | 2.4/5/6 GHz | WPA2/WPA3 Personal | Enabled | Enabled | Enabled |
| Will of D. (Guest) | 2.4/5 GHz | WPA2 Personal | Disabled | Enabled | Disabled |
| Will of D. IoT | 2.4 GHz only | WPA2 Personal | Disabled | Disabled | Disabled |
## Rollback Procedures
### Rollback Family of D. Fast Roaming
If legacy devices (older IoT, smart TVs, casting devices) experience connectivity issues:
```bash
curl -k -H "X-API-KEY: $UNIFI_API_KEY" -H "Content-Type: application/json" -X PUT \
-d '{
"type": "STANDARD",
"name": "Family of D.",
"enabled": true,
"network": {"type": "SPECIFIC", "networkId": "fb44c9bf-1534-4a98-9c7e-6aee4bf4069a"},
"securityConfiguration": {
"type": "WPA2_WPA3_PERSONAL",
"fastRoamingEnabled": false,
"passphrase": "ILoveNaomi2025",
"pmfMode": "OPTIONAL",
"saeConfiguration": {"anticloggingThresholdSeconds": 5, "syncTimeSeconds": 5},
"wpa3FastRoamingEnabled": false
},
"multicastToUnicastConversionEnabled": false,
"clientIsolationEnabled": false,
"hideName": false,
"uapsdEnabled": false,
"broadcastingFrequenciesGHz": [5, 6, 2.4],
"bandSteeringEnabled": true,
"arpProxyEnabled": false,
"bssTransitionEnabled": true,
"advertiseDeviceName": false
}' \
"https://192.168.1.1/proxy/network/integration/v1/sites/88f7af54-98f8-306a-a1c7-c9349722b1f6/wifi/broadcasts/b2784680-7b04-4c8a-9098-19aced53fc89"
```
### Rollback Guest BSS Transition
```bash
curl -k -H "X-API-KEY: $UNIFI_API_KEY" -H "Content-Type: application/json" -X PUT \
-d '{
"type": "STANDARD",
"name": "Will of D.",
"enabled": true,
"network": {"type": "SPECIFIC", "networkId": "02364634-a782-4b58-a33b-48b48f492210"},
"securityConfiguration": {
"type": "WPA2_PERSONAL",
"fastRoamingEnabled": false,
"passphrase": "EmergencyFood2025"
},
"multicastToUnicastConversionEnabled": false,
"clientIsolationEnabled": false,
"hideName": false,
"uapsdEnabled": false,
"broadcastingFrequenciesGHz": [5, 2.4],
"bandSteeringEnabled": true,
"arpProxyEnabled": false,
"bssTransitionEnabled": false,
"advertiseDeviceName": false
}' \
"https://192.168.1.1/proxy/network/integration/v1/sites/88f7af54-98f8-306a-a1c7-c9349722b1f6/wifi/broadcasts/a2cdccb6-d054-47ad-ab14-62cae625b6af"
```
### Delete Traffic Matching Rule
```bash
curl -k -H "X-API-KEY: $UNIFI_API_KEY" -X DELETE \
"https://192.168.1.1/proxy/network/integration/v1/sites/88f7af54-98f8-306a-a1c7-c9349722b1f6/traffic-matching-lists/e7f06077-1a11-4355-88df-185837ba29df"
```
## Troubleshooting
### WiFi Call Drops During Roaming
1. Verify fast roaming is enabled: check `fastRoamingEnabled` on the SSID
2. Check if the phone supports 802.11r (most phones since ~2018 do)
3. Look for excessive AP handoffs in UniFi client history
4. Check RSSI values - phones may be roaming too aggressively
### WiFi Call Fails to Establish
1. Verify firewall allows UDP 500, 4500 outbound from the client's zone
2. Check DNS resolution - AT&T WiFi calling needs to resolve carrier domains
3. Verify no DPI/IDS rules are blocking IPSec traffic
4. Check if the phone is on the correct SSID (not IoT SSID)
### Poor Call Quality (Jitter/Latency)
1. Check for airtime contention on the AP (too many 2.4GHz clients)
2. Verify band steering is pushing voice clients to 5/6GHz
3. Check if multicast-to-unicast is reducing broadcast noise
4. Review SQM/QoS settings on the WAN interface
## Related Documents
- [[unifi-network-optimization-plan.md|UniFi Network Optimization Plan]]
- [[unifi-execution-plan.md|UniFi Execution Plan]]