# Network Architecture *Homelab network topology and configuration* --- ## Overview The homelab uses a multi-layered network architecture with external access via Cloudflare, internal services through Nginx Proxy Manager, and mesh VPN for secure remote access. --- ## Network Topology ``` ┌────────────────────────────────────────────────────────────────────┐ │ INTERNET │ │ (Public IP via ISP) │ └────────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────┐ │ CLOUDFLARE │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ DNS │ │ Proxy │ │ Tunnels │ │ │ │ vish.gg │ │ vish.gg │ │ (if used) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └────────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────┐ │ HOME NETWORK │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Router │ │ Switch │ │ WiFi AP │ │ │ │ (Gateway) │ │ (Managed) │ │ (Ubiquiti) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ └──────────────────┬────────────────────┘ │ │ │ │ │ ┌──────┴──────┐ │ │ │ VLANs │ │ │ │ 10 (MGMT) │ │ │ │ 20 (IOT) │ │ │ │ 30 (MAIN) │ │ │ └─────────────┘ │ └────────────────────────────────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ ATLANTIS │ │ CALYPSO │ │ NUC │ │ (NAS) │ │ (NAS) │ │ (HA) │ └───────────┘ └───────────┘ └───────────┘ ``` --- ## IP Address Scheme ### Subnet Configuration | VLAN | Network | Gateway | DHCP Range | Purpose | |------|---------|---------|------------|---------| | 10 (MGMT) | 192.168.0.0/24 | .1 | .100-.150 | Infrastructure | | 20 (IOT) | 192.168.1.0/24 | .1 | .100-.200 | Smart home | | 30 (GUEST) | 192.168.2.0/24 | .1 | .100-.150 | Guest access | ### Static Assignments | Host | IP | MAC | Purpose | |------|-----|-----|---------| | Atlantis | 192.168.0.200 | - | Primary NAS (DS1823xs+) | | Calypso | 192.168.0.250 | - | Secondary NAS (DS723+), runs NPM | | Guava | 192.168.0.100 | - | TrueNAS Scale workstation | | PVE | 192.168.0.205 | - | Proxmox hypervisor | | Pi-5 | 192.168.0.66 | - | Raspberry Pi 5 | | Homelab VM | 192.168.0.210 | - | Proxmox VM, monitoring | --- ## Port Forwarding ### External Access | Service | External Port | Internal IP | Internal Port | Protocol | |---------|---------------|-------------|----------------|----------| | NPM HTTP | 80 | 192.168.0.250 | 80 | HTTP | | NPM HTTPS | 443 | 192.168.0.250 | 443 | HTTPS | | Headscale | 8443 | 192.168.0.250 | 8085 | TCP (control server) | | Plex | 32400 | 192.168.0.200 | 32400 | TCP | ### Internal Only (No Port Forward) | Service | Internal IP | Port | Access Method | |---------|-------------|------|----------------| | Grafana | 192.168.0.210 | 3000 | VPN only | | Prometheus | 192.168.0.210 | 9090 | VPN only | | Home Assistant | 192.168.12.202 | 8123 | VPN only (via GL-MT3000 subnet) | | Authentik | 192.168.0.250 | 9000 | VPN only | | Vaultwarden | 192.168.0.200 | 8080 | VPN only | --- ## DNS Configuration ### Primary: Pi-hole / AdGuard ``` Upstream DNS: - 1.1.1.1 (Cloudflare) - 8.8.8.8 (Google) Local Domains: - vish.local - vish.gg ``` ### Local DNS Entries | Hostname | IP | Description | |----------|-----|-------------| | atlantis | 192.168.0.200 | Primary NAS (DS1823xs+) | | calypso | 192.168.0.250 | Secondary NAS (DS723+) | | guava | 192.168.0.100 | TrueNAS Scale | | pve | 192.168.0.205 | Proxmox host | | homelab | 192.168.0.210 | Proxmox VM | | pi-5 | 192.168.0.66 | Raspberry Pi 5 | --- ## Reverse Proxy Flow ### External Request (vish.gg) ``` 1. User → https://service.vish.gg 2. Cloudflare DNS → resolves to home IP 3. Home Router → forwards to 192.168.0.250:443 4. NPM (Calypso) → terminates SSL 5. Authentik (if SSO) → authenticates 6. Backend service → responds 7. NPM → returns to user ``` ### Internal Request ``` 1. User → http://service.local (or IP) 2. Pi-hole/AdGuard → resolves to internal IP 3. NPM (optional) or direct → service 4. Response → user ``` --- ## VPN Configuration ### Headscale (Primary Mesh VPN) All nodes use the Tailscale client pointed at the self-hosted Headscale control server. | Setting | Value | |---------|-------| | Control Server | `headscale.vish.gg:8443` | | Host | Calypso (192.168.0.250) | | Admin UI | Headplane (via NPM at :8443/admin) | | DERP Servers | Tailscale public DERP map | | MagicDNS suffix | `tail.vish.gg` | | IP Range | 100.64.0.0/10 | | Exit Nodes | atlantis, calypso, setillo, vish-concord-nuc, seattle, homeassistant | ### WireGuard (Point-to-Point, Secondary) | Setting | Value | |---------|-------| | Server | Concord NUC (wg-easy, port 51820) | | Interface | Dynamic | | Use Case | Clients that can't run Tailscale | --- ## VLAN Configuration ### Management VLAN (10) - Devices: NAS, switches, APs - Access: Admin only - Internet: Full ### IoT VLAN (20) - Devices: Smart home, cameras - Access: Restricted - Internet: Filtered (Pi-hole) - Isolation: Yes ### Main VLAN (30) - Devices: Personal devices - Access: Full - Internet: Full --- ## Firewall Rules ### Router (UFW/iptables) ```bash # Allow established connections iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT # Allow SSH iptables -A INPUT -p tcp --dport 22 -j ACCEPT # Allow HTTP/HTTPS iptables -A INPUT -p tcp --dport 80 -j ACCEPT iptables -A INPUT -p tcp --dport 443 -j ACCEPT # Allow WireGuard iptables -A INPUT -p udp --dport 51820 -j ACCEPT # Drop everything else iptables -A INPUT -j DROP ``` ### Docker Network ```yaml # docker-compose.yml networks: default: driver: bridge ipam: config: - subnet: 172.20.0.0/24 ``` --- ## Monitoring ### Network Metrics | Metric | Source | Dashboard | |--------|--------|-----------| | Bandwidth | Node Exporter | Network | | Packet loss | Prometheus | Network | | DNS queries | Pi-hole | DNS | | VPN connections | WireGuard | VPN | --- ## Troubleshooting ### Cannot Access Service 1. **Check DNS:** `nslookup service.vish.local` 2. **Check connectivity:** `ping 192.168.0.x` 3. **Check port:** `nc -zv 192.168.0.x 443` 4. **Check service:** `curl -I http://localhost:PORT` 5. **Check firewall:** `sudo iptables -L` ### Slow Network 1. Check bandwidth: `iperf3 -c 192.168.0.x` 2. Check for interference (WiFi) 3. Check switch port speed 4. Check for broadcast storms ### VPN Issues 1. Check WireGuard status: `wg show` 2. Check Headscale nodes: `headscale nodes list` 3. Verify firewall allows UDP 51820 4. Check NAT traversal --- ## Links - [Cloudflare Setup](../infrastructure/cloudflare-dns.md) - [WireGuard Guide](../services/individual/wg-easy.md) - [Headscale Setup](../infrastructure/tailscale-setup-guide.md) - [Port Forwarding](../infrastructure/port-forwarding-configuration.md)