rufusking/infrastructure
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
infrastructure/network_index.md

19 KiB
Raw Blame History

KingDezigns Network Documentation Index

Last Updated: 2026-08-19

This index provides a structured overview of all VLANs, servers, and firewall policies in the KingDezigns network.
Each section links to its own dedicated Markdown file for clarity and modularity.

📁 VLAN Documentation

🔧 Core VLANs

🧑‍💻 Trusted User VLANs

🏠 Smart Home & Guest VLANs

🧪 Server & Lab VLAN

🖥️ Server Documentation

Core Services

Network Hardware

🔥 Firewall Policies

🛡️ Security Stack

Intrusion Prevention

  • CrowdSec — installed on HAS as a native HA add-on
    • Agent reads NPM, HA, and SSH logs via journald
    • 60 active detection scenarios
    • Community blocklist updates every 2 hours
    • Firewall Bouncer enforces bans at nftables level
    • Email alerts on every ban decision
    • All LAN VLANs whitelisted — internal IPs can never be banned
    • Applies automatically to every service proxied through NPM, including Forgejo and Fund Tracker — no per-service configuration needed
    • See Home Assistant Server for full configuration details

Perimeter Defense (per server)

  • Fail2Ban — NAS16 (active), PLEX32 (active), NAS08 (recommended)
    • ignoreip includes 192.168.150.0/24 to prevent HAS proxy IP from being banned
    • Real IP forwarding configured on NAS16 (nginx + Apache) and NAS08

DNS-level Protection

  • Pi-hole — NAS08 (192.168.150.35)
    • Blocks ads, trackers, and malicious domains for all VLANs
    • All VLANs forced to use Pi-hole via global firewall rule 20001
    • Local DNS overrides required for any internally-hosted service accessed by its public hostname from within the LAN (e.g. cloud.kingdezigns.com → 192.168.150.30), to avoid NAT hairpin failures. See server_nas08.md ONLYOFFICE section for a documented example and fix.

Application-level Auth (per service, where applicable)

  • Fund Tracker — session-cookie auth (httponly, bcrypt-hashed passwords), account lockout after 5 failed attempts, forced password change on new/seeded accounts, versioned legal-document acceptance gating. See server_fundtracker.md.

🌐 Network Architecture Overview

This documentation set is designed around:

  • Clear segmentation
  • Explicit inter-VLAN access
  • Isolation of untrusted devices
  • Preservation of Home Assistant functionality
  • AI-friendly structure and formatting
  • Layered security — DNS filtering, intrusion prevention, firewall enforcement

Security Layer Model

Internet
    ↓
UCG Max — firewall, VLAN segmentation, geo-blocking (future)
    ↓
CrowdSec Firewall Bouncer — nftables ban enforcement
    ↓
NPM on HAS — single ingress, SSL termination
    ↓
CrowdSec Agent — log analysis, attack detection
    ↓
Backend Services (NAS08, NAS16, PLEX32)
    ↓
Fail2Ban — last-line brute force protection
    ↑
Pi-hole — DNS-level ad/tracker/malware blocking (all VLANs)

🔑 SSH Key Authentication Map

SSH key authentication is configured between the following machines — no passwords required:

From To Purpose
KingDezigns001 PLEX32 (192.168.150.45) Remote launcher script
KingDezigns001 NAS08 (192.168.150.35) Direct SSH access
KingDezigns001 NAS16 (192.168.150.40) Direct SSH access
PLEX32 NAS08 (192.168.150.35) Backup script disk stats via SSH

Key type: ED25519. Keys generated per machine — not shared.

🖥️ KingDezigns001 — Admin Workstation Tools

KingDezigns001 is the primary Linux administrative workstation on VLAN 20 (Trusted).

Remote Launcher

A menu-driven launcher script provides one-click access to run scripts on PLEX32:

  • Script: ~/scripts/plex32_launcher.sh
  • Desktop shortcut: ~/Desktop/PLEX32-Launcher.desktop
  • Terminal: gnome-terminal

Menu Options

Option Runs on Script
1) Update Check PLEX32 /usr/scripts/plex32/plex32_update_check.sh
2) Health Report PLEX32 /usr/scripts/plex32/plex32_health_report.sh
3) Plex32 Backup PLEX32 /usr/scripts/plex32/plex32_backup.sh

🧠 Notes for AI Systems

  • File update workflow (read this first): When asked to "update" a project file, take the existing file, make the requested changes, and present the updated file for download — do not explain the read-only/re-upload mechanism unless something about the process itself is actually in question. The user re-uploads it to the Project themselves. No caveat, disclaimer, or explanation of Claude's file access model is needed before or after doing this — just do it.
  • Each file is self-contained and structured consistently.
  • Section headers follow a predictable pattern for easy parsing.
  • No duplicated firewall rules — all rules live in firewall_policies.md.
  • CrowdSec configuration lives entirely on HAS — see server_homeassistant.md.
  • VLAN files contain:
    • Purpose
    • Access types
    • Subnet
    • Expected devices
    • Security rules
    • AI summary
  • Plex Media Server migrated from NAS08 to PLEX32 (dedicated Dell Wyse 5070) on 2026-06-18 — see server_plex32.md.
  • PLEX32 now runs Plex + Tautulli with Intel Quick Sync hardware transcoding — optimized 2026-06-20.
  • KingDezigns001 has SSH keys to all VLAN 50 servers — passwordless access for all admin tasks.
  • PLEX32 has SSH key to NAS08 — required for backup script to fetch disk stats.
  • NAS08 Nextcloud update check runs daily at 7AM — /usr/scripts/omv/nextcloud_update_check.sh — emails HTML report with copy-paste occ commands. Never use the browser UI for Nextcloud app updates (causes Apache segfault → maintenance mode deadlock).
  • NAS08 Nextcloud update check — core-update false negative fixed (2026-07-25): the script previously checked app updates only (occ app:update) and had no code path for Nextcloud core/server releases, so it silently missed a core update (34.0.1 → 34.0.2) and emailed a false "up to date" report. Fixed by adding a core check via occ update:check, correcting the emailed Compose commands to the real path (/kingdezignsnas/Docker/Compose/nextcloud/, root-only, non-default filenames requiring -f nextcloud.yml -f compose.override.yml), and fixing a bash quoting bug that made emailed multi-line commands unreadable. Also documented: the official Nextcloud Docker image auto-upgrades on container restart via its own entrypoint — checking version status immediately after up -d can race that process and show a stale version for ~30 seconds. Full detail in server_nas08.md.
  • NAS08 Nextcloud Office editing uses ONLYOFFICE Document Server (free Community Edition) as of 2026-07-18. Only one Office integration app should ever be enabled at a time (exception: the Collabora trial below, run as a time-boxed disable/enable swap, never simultaneous). Requires a Pi-hole local DNS override for cloud.kingdezigns.com, ALLOW_PRIVATE_IP_ADDRESS=true on the container, and matching JWT secrets between Nextcloud and the container. Full details and troubleshooting history in server_nas08.md.
  • NAS08 Collabora Online trial (2026-07-21, ongoing): A second Office editor, Collabora Online (CODE), was deployed as a standalone Docker container (collabora, its own OMV Compose project "Collabora Office") for a head-to-head reliability trial against ONLYOFFICE — triggered by confirmed ONLYOFFICE bugs (conditional formatting crashing on formula cells; silent reverts to hours-old document versions). Only one Office app is ever enabled in Nextcloud at a time — currently richdocuments/Collabora is enabled, onlyoffice is disabled but still installed for easy rollback. Public URL https://collabora.kingdezigns.com/, requires its own Pi-hole local DNS override and a WOPI allow-list (192.168.150.35). First real-document test succeeded with a notably fast load time. Full config, setup troubleshooting, and rollback steps in server_nas08.md.
  • NAS08 Collabora stock/fund price macro integration (2026-07-22, working): The ONLYOFFICE FUNDPRICE/FUNDPRICE_HIST/STOCKPRICE/STOCKTIME custom functions were ported to Collabora as a LibreOffice Basic module (StockFunctions.bas), calling the same STOCKPROXY backend with no backend changes required. Two coolwsd.xml server-config changes were required — macro execution enabling and a net.lok_allow hostname allowlist entry for stocks.kingdezigns.com — plus a fix to the previously non-functional stocks.kingdezigns.com Pi-hole DNS override. Confirmed working with a live price pull as of 2026-07-22. Full troubleshooting detail, exact config edits, and remaining follow-up items (recreating the full ~50-fund table, conditional-formatting re-test, recalc performance) in server_nas08.md.
  • NAS08 systemd-resolved DNS bug (fixed 2026-07-18): a stray global DNS= override in /etc/systemd/resolved.conf caused duplicate/incorrect DNS answers for internal hostnames network-wide on that host. Any future "works from browser but fails from a container/script on NAS08" symptom should check resolvectl status for stray global DNS servers first.
  • NAS08 STOCKPROXY service (2026-07-21): Self-hosted Flask API, Docker container stockproxy (~/docker/stockproxy/), port 5005, public URL https://stocks.kingdezigns.com/ proxied via NPM on HAS (see Proxy Hosts table in server_homeassistant.md). Supplies current + historical mutual fund prices to ONLYOFFICE custom functions (FUNDPRICE, FUNDPRICE_HIST) via Yahoo Finance, scraped server-side to dodge the browser CORS block that rules out calling Yahoo directly from a spreadsheet macro. Finnhub was evaluated first but dropped from this service — confirmed no mutual fund NAV coverage on the free tier. Current-price cache: 15 min in-memory. Historical-price cache: permanent, SQLite. All endpoints require a shared-secret key param (Vaultwarden). Built to support the "HSA Investiments Choices" tab in Rufus Retirement Account Tracking 2026.xlsx. stocks.kingdezigns.com A record added to the daily Dreamhost DDNS refresh script. Full config and known limitations in server_nas08.md.
  • NAS08 RANK.EQ Err:522 circular reference fix (2026-07-23, working): The "HSA Investiments Choices" fund-ranking formula broke with a circular-reference error on any sheet edit (worked fine on load) because it depended on ~50 cells fed by live FUNDPRICE/FUNDPRICE_HIST network calls. Fixed with a button-triggered LibreOffice Basic macro that snapshots the live price columns into static value-only columns via setDataArray(), with percent-change and rank formulas rebuilt to read from the static snapshot instead of the live columns. Full root-cause analysis and macro in server_nas08.md.
  • NAS08 Collabora Finnhub removal (2026-07-23, working): STOCKPRICE/STOCKTIME (Finnhub-backed equity functions) errored due to a missing net.lok_allow entry for Finnhub. Instead of allowlisting Finnhub, it was removed entirely — FUNDPRICE (STOCKPROXY) now covers equity tickers too, and a new FUNDTIME function replaces STOCKTIME, returning STOCKPROXY's resolved_date (date only, not a time-of-day timestamp — accepted tradeoff). No coolwsd.xml changes required. Full detail in server_nas08.md.
  • Synaplan AI integration (added 2026-07-18, not yet functional): Nextcloud connector app installed, but the required self-hosted Synaplan backend stack (PHP/MariaDB/Qdrant/optional Ollama) has not been deployed. Treat as a future project, not a bug — see server_nas08.md for details before troubleshooting.
  • Forgejo self-hosted Git server (added 2026-07-26): Deployed on NAS16 (192.168.150.40) via Docker Compose — chosen over Gitea for non-profit/community governance (Codeberg e.V.). Public web UI at https://forgejo.kingdezigns.com/ (proxied via NPM on HAS), SSH git access on port 2222 (LAN-only, no external port-forward). Provides version control with in-browser file editing/history for the 07 - Projects folder on NAS16's share, organized as one Forgejo org per host (NAS08, NAS16, PLEX32) with a <hostname>-scripts repo in each. Data (/opt/forgejo/data) folded into the existing nas16-backup.sh job. A companion forgejo_autosync.sh script (not yet scheduled as of this writing) auto-commits/pushes any uncommitted changes on a timer as a safety net alongside normal manual commits. Full setup, config, and troubleshooting history in server_forgejo.md.
  • Fund Tracker multi-profile mutual fund/stock tracker (added 2026-08-17): Deployed on NAS16 (192.168.150.40) via Docker Compose — FastAPI + PostgreSQL, containers fundtracker_api/fundtracker_db. Public web UI at https://funds.kingdezigns.com/ (proxied via NPM on HAS, Force SSL). Core design: security data (ticker, price history, group classification) is shared across all profiles and synced once regardless of how many profiles track it; each profile's holdings, cost basis, and watchlist membership are private. Scoring built from quality (risk-adjusted), opportunity (quality + genuine price dip, requires both a return z-score AND a drawdown-from-high to agree), combined (harmonic mean of quality+opportunity), and rebound (peer-relative "usually near the top of its group, currently collapsed" detector, reconstructed retroactively from existing price history) scores. Market data via yfinance + curl_cffi Chrome-impersonation session — required to avoid Yahoo Finance's bot-detection blocking, and a real fix (not a sandbox artifact). Session-cookie auth (httponly, bcrypt), admin role with anonymized cross-profile Census and versioned legal-document (Terms of Use + Investment Disclaimer) publishing — a version bump immediately requires every profile to re-accept. Daily sync + personalized-per-profile email report runs via an in-process APScheduler inside the container at 06:00 UTC, not an OMV Scheduled Job. Full architecture, scoring methodology, deployment pattern (code-only changes = folder swap + restart; dependency changes = rebuild; compose/env changes = up -d; structural DB migrations require a pg_dump backup first), and known-issue history in server_fundtracker.md.
  • Fund Tracker — Portfolio/transaction tracking system documented 2026-08-19 (built in an earlier session, previously undocumented in this project): a buy-lot/sale/split register sits alongside the scoring system — FIFO/LIFO/Specific-ID sale matching, split handling that only touches lots active before the split date, a GET /portfolio/register endpoint, and edit/delete with lock-on-sale-allocation protection (deleting the sale restores shares and unlocks the lot). Full endpoint list, data model, and known deployment gotchas now in server_fundtracker.md's dedicated Portfolio section.
  • Fund Tracker Portfolio UI — three-level collapsible register (2026-08-19): the Portfolio page now renders Ticker (collapsed by default) → Buy Lot → Sale(s), instead of showing every buy lot for every ticker at once. Frontend-only change to portfolio.html; deployed via scp to a /tmp scratch path → sudo cp into the root-owned /Kingdezignsnas16/fundtracker/ project dir → sudo docker restart fundtracker_api (no rebuild needed for a static-file-only change, consistent with the documented code-only deployment pattern). Full detail in server_fundtracker.md.

📌 Future Expansion

Additional files may be added for:

  • Device inventories
  • Application-specific firewall rules
  • Backup and recovery procedures
  • Monitoring and alerting configuration
  • CrowdSec Console dashboard enrollment
  • Geo-blocking configuration on UCG Max
  • Authelia / forward authentication layer
  • Expand remote launcher to cover NAS08 and NAS16 scripts
  • Synaplan self-hosted AI stack deployment (PHP backend, MariaDB, Qdrant, optional Ollama) — scope resource requirements and deployment plan when ready
  • Collabora vs. ONLYOFFICE trial decision (started 2026-07-21) — once a winner is chosen, update server_nas08.md and this index to reflect the final state (remove trial framing, decommission or keep the losing container, update firewall/NPM docs if the losing editor's proxy host is removed)
  • STOCKPROXY hardening — not yet stress-tested at full ~50-ticker scale for Yahoo-side rate limiting; revisit if widespread simultaneous lookup failures are observed
  • Fund Tracker — pending feature work (as of 2026-08-17, not yet built): self-service user account page (email update, relocated change-password), stronger primary-admin delete/demote protection, Eastern-time display throughout (currently UTC), always-visible logout control in the sidebar (currently inconsistent across pages per user report), confirmation of cookie/session behavior over the new HTTPS domain, fully-qualified-domain links everywhere (email + in-app) instead of the internal IP, public self-service signup with an admin on/off toggle and disclaimer acceptance, and open questions on geo-blocking / additional security hardening / anti-infiltration monitoring / PII collection policy. See the dedicated handoff summary provided at the end of the deployment conversation before starting this work.
  • Fund Tracker — pre-existing documentation gap fixed 2026-08-17: the Forgejo proxy host (192.168.150.40:3000) was missing from server_homeassistant.md's Current Proxy Hosts table despite Forgejo being deployed and documented since 2026-07-26 — added along with the new Fund Tracker entry.
  • Fund Tracker — Portfolio system testing ongoing (as of 2026-08-19): the buy-lot/sale/split register is working but not yet exhaustively tested. Per the project's own handoff notes, remaining test cases include: purchases entered out of chronological order, sales entered against multiple lots, partial vs. complete sales, sale deletion, editing an unmatched lot, splits entered after transactions exist, reverse splits, purchases made after a historical split, lots fully sold before a split, and confirming one ticker's sales don't affect another ticker's lots. Continue from the current known-good state rather than rebuilding — see the Portfolio section of server_fundtracker.md.

✔️ End of Index